├── _static └── README ├── _config.yml ├── Reference.md ├── RESTful_HDF5.png ├── Diagram.md ├── Diagram.rst ├── index.md ├── Reference.rst ├── .github └── workflows │ └── validate.yml ├── CommonResponseHeaders.md ├── index.rst ├── CommonResponseHeaders.rst ├── Introduction └── index.rst ├── make.bat ├── CommonRequestHeaders.md ├── CommonRequestHeaders.rst ├── Makefile ├── DatatypeOps ├── index.md ├── index.rst ├── DELETE_Datatype.md ├── DELETE_Datatype.rst ├── GET_Datatype.md ├── GET_Datatype.rst ├── GET_Datatypes.md └── POST_Datatype.md ├── AttrOps ├── index.md ├── index.rst ├── DELETE_Attribute.md ├── DELETE_Attribute.rst └── GET_Attribute.md ├── README.md ├── CommonErrorResponses.md ├── CommonErrorResponses.rst ├── UsingIteration.md ├── UsingIteration.rst ├── DomainOps ├── DELETE_Domain.md ├── DELETE_Domain.rst ├── index.md ├── index.rst ├── PUT_Domain.md ├── PUT_Domain.rst ├── GET_Domain.md └── GET_Domain.rst ├── GroupOps ├── index.md ├── DELETE_Group.md ├── index.rst ├── DELETE_Group.rst ├── DELETE_Link.md ├── DELETE_Link.rst ├── GET_Group.md ├── GET_Group.rst ├── GET_Groups.md └── POST_Group.md ├── Authorization.md ├── Hypermedia.md ├── Authorization.rst ├── Hypermedia.rst ├── DatasetOps ├── DELETE_Dataset.md ├── POST_Value.md ├── DELETE_Dataset.rst ├── PUT_DatasetShape.md ├── POST_Value.rst ├── index.md ├── PUT_DatasetShape.rst ├── index.rst ├── GET_Datasets.md ├── GET_Dataset.md ├── GET_Dataset.rst ├── GET_Datasets.rst └── GET_DatasetShape.md ├── Resources.rst ├── .validaterc ├── AclOps ├── PUT_ACL.md ├── GET_ACL.md ├── PUT_ACL.rst ├── GET_ACLs.md ├── GET_ACL.rst ├── index.md └── index.rst └── Resources.md /_static/README: -------------------------------------------------------------------------------- 1 | static files 2 | -------------------------------------------------------------------------------- /_config.yml: -------------------------------------------------------------------------------- 1 | theme: jekyll-theme-cayman -------------------------------------------------------------------------------- /Reference.md: -------------------------------------------------------------------------------- 1 | Reference 2 | ========= 3 | -------------------------------------------------------------------------------- /RESTful_HDF5.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/HDFGroup/hdf-rest-api/HEAD/RESTful_HDF5.png -------------------------------------------------------------------------------- /Diagram.md: -------------------------------------------------------------------------------- 1 | Diagram of REST operations 2 | ========================== 3 | 4 | alternate text 5 | -------------------------------------------------------------------------------- /Diagram.rst: -------------------------------------------------------------------------------- 1 | *************************** 2 | Diagram of REST operations 3 | *************************** 4 | 5 | 6 | .. image:: RESTful_HDF5.png 7 | :width: 100 % 8 | :alt: alternate text 9 | :align: right -------------------------------------------------------------------------------- /index.md: -------------------------------------------------------------------------------- 1 | HDF REST API Developer Documentation 2 | ==================================== 3 | 4 | This is the developer documentation for the HDF REST API. 5 | 6 | Contents: 7 | 8 | Indices and tables 9 | ================== 10 | 11 | - genindex 12 | - modindex 13 | - search 14 | 15 | -------------------------------------------------------------------------------- /Reference.rst: -------------------------------------------------------------------------------- 1 | ################### 2 | Reference 3 | ################### 4 | 5 | .. toctree:: 6 | :maxdepth: 2 7 | 8 | Authorization 9 | CommonRequestHeaders 10 | CommonResponseHeaders 11 | CommonErrorResponses 12 | Diagram 13 | Hypermedia 14 | Resources 15 | UsingIteration 16 | 17 | 18 | -------------------------------------------------------------------------------- /.github/workflows/validate.yml: -------------------------------------------------------------------------------- 1 | # This workflow will do a clean install of node dependencies, cache/restore them, build the source code and run tests across different versions of node 2 | # For more information see: https://help.github.com/actions/language-and-framework-guides/using-nodejs-with-github-actions 3 | 4 | name: Node.js CI 5 | 6 | on: [push, workflow_dispatch] 7 | 8 | jobs: 9 | validateOpenApiSpec: 10 | 11 | runs-on: ubuntu-latest 12 | 13 | steps: 14 | - uses: actions/checkout@v2 15 | - name: Use Node.js 16 | uses: actions/setup-node@v2 17 | with: 18 | node-version: 16 19 | - run: npm install -g ibm-openapi-validator 20 | - run: lint-openapi openapi.yaml 21 | -------------------------------------------------------------------------------- /CommonResponseHeaders.md: -------------------------------------------------------------------------------- 1 | Common Response Headers 2 | ======================= 3 | 4 | The following describes some of the common response lines returned by the HDF REST API. 5 | 6 | > - Status Line: the first line of the response will always be: "`HTTP/1.1`" followed by 7 | > a status code (e.g. 200) followed by a reason message (e.g. "`OK`"). For errors, an additional error message may be included on this line. 8 | > 9 | > - Content-Length: the response size in bytes. 10 | > - Etag: a hash code that indicates the state of the requested resource. If the client 11 | > sees the same Etag value for the same request, it can assume the resource has not changed since the last request. 12 | > 13 | > - Content-Type: the mime type of the response. 14 | 15 | -------------------------------------------------------------------------------- /index.rst: -------------------------------------------------------------------------------- 1 | .. HDF REST API documentation master file, created by 2 | sphinx-quickstart on Mon Jul 9 10:29:28 2018. 3 | You can adapt this file completely to your liking, but it should at least 4 | contain the root `toctree` directive. 5 | 6 | HDF REST API Developer Documentation 7 | ==================================== 8 | 9 | This is the developer documentation for the HDF REST API. 10 | 11 | Contents: 12 | 13 | .. toctree:: 14 | :maxdepth: 2 15 | 16 | Introduction/index 17 | DomainOps/index 18 | GroupOps/index 19 | DatasetOps/index 20 | DatatypeOps/index 21 | AttrOps/index 22 | Types/index 23 | AclOps/index 24 | Reference 25 | 26 | 27 | 28 | Indices and tables 29 | ================== 30 | 31 | * :ref:`genindex` 32 | * :ref:`modindex` 33 | * :ref:`search` 34 | -------------------------------------------------------------------------------- /CommonResponseHeaders.rst: -------------------------------------------------------------------------------- 1 | *************************** 2 | Common Response Headers 3 | *************************** 4 | 5 | The following describes some of the common response lines returned by the HDF REST API. 6 | 7 | * Status Line: the first line of the response will always be: "``HTTP/1.1``" followed by 8 | a status code (e.g. 200) followed by a reason message (e.g. "``OK``"). For errors, 9 | an additional error message may be included on this line. 10 | 11 | * Content-Length: the response size in bytes. 12 | 13 | * Etag: a hash code that indicates the state of the requested resource. If the client 14 | sees the same Etag value for the same request, it can assume the resource has not 15 | changed since the last request. 16 | 17 | * Content-Type: the mime type of the response. 18 | 19 | -------------------------------------------------------------------------------- /Introduction/index.rst: -------------------------------------------------------------------------------- 1 | ################### 2 | Introduction 3 | ################### 4 | 5 | The HDF REST API is an interface to HDF5 data stored on network-based architectures. 6 | The HDF REST API has provisions to support CRUD (create, read, update and delete) operations on 7 | the full spectrum of HDF5 objects including: groups, links, datasets, attributes, and committed 8 | data types. See https://support.hdfgroup.org/pubs/papers/RESTful_HDF5.pdf for more information on the 9 | RESTful HDF5 interface. 10 | 11 | As a REST-based API, implementations can be developed in a variety of languages, such as 12 | JavaScript, Python, C, and other common languages. Some services which implement the HDF REST API are: 13 | 14 | HDF Kita: https://www.hdfgroup.org/hdf-kita 15 | 16 | H5serv: https://github.com/HDFGroup/h5serv 17 | 18 | HDF5 REST VOL: https://bitbucket.hdfgroup.org/users/jhenderson/repos/rest-vol/browse -------------------------------------------------------------------------------- /make.bat: -------------------------------------------------------------------------------- 1 | @ECHO OFF 2 | 3 | pushd %~dp0 4 | 5 | REM Command file for Sphinx documentation 6 | 7 | if "%SPHINXBUILD%" == "" ( 8 | set SPHINXBUILD=sphinx-build 9 | ) 10 | set SOURCEDIR=. 11 | set BUILDDIR=_build 12 | set SPHINXPROJ=HDFRESTAPI 13 | 14 | if "%1" == "" goto help 15 | 16 | %SPHINXBUILD% >NUL 2>NUL 17 | if errorlevel 9009 ( 18 | echo. 19 | echo.The 'sphinx-build' command was not found. Make sure you have Sphinx 20 | echo.installed, then set the SPHINXBUILD environment variable to point 21 | echo.to the full path of the 'sphinx-build' executable. Alternatively you 22 | echo.may add the Sphinx directory to PATH. 23 | echo. 24 | echo.If you don't have Sphinx installed, grab it from 25 | echo.http://sphinx-doc.org/ 26 | exit /b 1 27 | ) 28 | 29 | %SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% 30 | goto end 31 | 32 | :help 33 | %SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% 34 | 35 | :end 36 | popd 37 | -------------------------------------------------------------------------------- /CommonRequestHeaders.md: -------------------------------------------------------------------------------- 1 | Common Request Headers 2 | ====================== 3 | 4 | The following describe common HTTP request headers as used in the HDF REST API: 5 | 6 | > - Request line: The first line of the request, the format is of the form HTTP verb (GET, PUT, DELETE, or POST) followed by the path to the resource (e.g. /group/<uuid>. Some operations take one or more query parameters (see relevant documentation) 7 | > - Accept: Specifies the media type that is acceptable for the response. Valid values are "application/json", and "*/*. In addition, GET/PUT/POST Value (see DatasetOps/GET\_Value, DatasetOps/PUT\_Value, DatasetOps/POST\_Value) support the value "application/octet-stream" 8 | > - Authorization: A string that provides the requester's credentials for the request. See Authorization 9 | > - Host: the domain (i.e. related collection of groups, datasets, and attributes) that the request should apply to 10 | > 11 | > Note: the host header can also be provided as a query parameter. Example: 12 | -------------------------------------------------------------------------------- /CommonRequestHeaders.rst: -------------------------------------------------------------------------------- 1 | *********************** 2 | Common Request Headers 3 | *********************** 4 | 5 | The following describe common HTTP request headers as used in the HDF REST API: 6 | 7 | * Request line: The first line of the request, the format is of the form HTTP verb (GET, PUT, DELETE, or POST) followed by the path to the resource (e.g. /group/. Some operations take one or more query parameters (see relevant documentation) 8 | * Accept: Specifies the media type that is acceptable for the response. Valid values are "application/json", and "*/*. In addition, GET/PUT/POST Value (see :doc:`DatasetOps/GET_Value`, :doc:`DatasetOps/PUT_Value`, :doc:`DatasetOps/POST_Value`) support the value "application/octet-stream" 9 | * Authorization: A string that provides the requester's credentials for the request. See :doc:`Authorization` 10 | * Host: the domain (i.e. related collection of groups, datasets, and attributes) that the request should apply to 11 | 12 | Note: the host header can also be provided as a query parameter. Example: https://data.hdfgroup.org:7258/?host=tall.test.data.hdfgroup.org 13 | -------------------------------------------------------------------------------- /Makefile: -------------------------------------------------------------------------------- 1 | # Minimal makefile for Sphinx documentation 2 | # 3 | 4 | # You can set these variables from the command line. 5 | SPHINXOPTS = 6 | SPHINXBUILD = sphinx-build 7 | SPHINXPROJ = HDFRESTAPI 8 | SOURCEDIR = . 9 | BUILDDIR = _build 10 | 11 | # User-friendly check for sphinx-build 12 | ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1) 13 | $(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/) 14 | endif 15 | 16 | # Put it first so that "make" without argument is like "make help". 17 | help: 18 | @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) 19 | 20 | .PHONY: help Makefile 21 | 22 | # Catch-all target: route all unknown targets to Sphinx using the new 23 | # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). 24 | %: Makefile 25 | @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) -------------------------------------------------------------------------------- /DatatypeOps/index.md: -------------------------------------------------------------------------------- 1 | Committed Datatypes 2 | =================== 3 | 4 | Committed datatypes (also known as "named types"), are objects that describe types. These types can be used in the creation of datasets and attributes. 5 | 6 | Committed datatypes can be linked to from a Group and can contain attributes, just like a dataset or group object. 7 | 8 | Creating committed datatypes 9 | ---------------------------- 10 | 11 | Use POST\_Datatype to create a new datatype. A complete description of the type must be sent with the POST request. 12 | 13 | Getting information about a committed datatype 14 | ---------------------------------------------- 15 | 16 | Use the GET\_Datatype operation to retrieve information about a committed datatype. To list all the committed datatypes within a domain use GET\_Datatypes. To list the committed types linked to a particular group use ../GroupOps/GET\_Links and examine link objects with a "collection" key of "datatypes". 17 | 18 | Deleting committed datatypes 19 | ---------------------------- 20 | 21 | Use DELETE\_Datatype to delete a datatype. Links from any group to the datatype will be deleted. 22 | 23 | List of Operations 24 | ------------------ 25 | -------------------------------------------------------------------------------- /AttrOps/index.md: -------------------------------------------------------------------------------- 1 | Attributes 2 | ========== 3 | 4 | Like datasets (see ../DatasetOps/index), attributes are objects that contain a homogeneous collection of elements and have associated type information. Attributes are typically small metadata objects that describe some aspect of the object (dataset, group, or committed datatype) that contains the attribute. 5 | 6 | Creating Attributes 7 | ------------------- 8 | 9 | Use PUT\_Attribute to create an attribute. If there is an existing attribute with the same name, it will be overwritten by this request. You can use GET\_Attribute to inquire if the attribute already exists or not. When creating an attribute, the attribute name, type and shape (for non-scalar attributes) is included in the request. 10 | 11 | Reading and Writing Data 12 | ------------------------ 13 | 14 | Unlike datasets, an attribute's data can not be read or written partially. Data can only be written as part of the PUT request. Reading the data of an attribute is done by GET\_Attribute. 15 | 16 | Listing attributes 17 | ------------------ 18 | 19 | Use GET\_Attributes to get information about all the attributes of a group, dataset, or committed datatype. 20 | 21 | Deleting Attributes 22 | ------------------- 23 | 24 | Use DELETE\_Attribute to delete an attribute. 25 | 26 | List of Operations 27 | ------------------ 28 | -------------------------------------------------------------------------------- /DatatypeOps/index.rst: -------------------------------------------------------------------------------- 1 | ####################### 2 | Committed Datatypes 3 | ####################### 4 | 5 | Committed datatypes (also known as "named types"), are objects that describe types. These 6 | types can be used in the creation of datasets and attributes. 7 | 8 | Committed datatypes can be linked to from a Group and can contain attributes, just like 9 | a dataset or group object. 10 | 11 | Creating committed datatypes 12 | ---------------------------- 13 | 14 | Use :doc:`POST_Datatype` to create a new datatype. A complete description of the 15 | type must be sent with the POST request. 16 | 17 | Getting information about a committed datatype 18 | ----------------------------------------------- 19 | 20 | Use the :doc:`GET_Datatype` operation to retrieve information about a committed datatype. 21 | To list all the committed datatypes within a domain use 22 | :doc:`GET_Datatypes`. To list the committed types linked to a particular group use 23 | :doc:`../GroupOps/GET_Links` and examine link objects with a "collection" key of 24 | "datatypes". 25 | 26 | Deleting committed datatypes 27 | ---------------------------- 28 | 29 | Use :doc:`DELETE_Datatype` to delete a datatype. Links from any group to the datatype 30 | will be deleted. 31 | 32 | List of Operations 33 | ------------------ 34 | 35 | .. toctree:: 36 | :maxdepth: 1 37 | 38 | DELETE_Datatype 39 | GET_Datatype 40 | GET_Datatypes 41 | POST_Datatype 42 | 43 | 44 | -------------------------------------------------------------------------------- /AttrOps/index.rst: -------------------------------------------------------------------------------- 1 | ######################## 2 | Attributes 3 | ######################## 4 | 5 | Like datasets (see :doc:`../DatasetOps/index`), attributes are objects that contain a 6 | homogeneous collection of elements 7 | and have associated type information. Attributes are typically small metadata objects 8 | that describe some aspect of the object (dataset, group, or committed datatype) that 9 | contains the attribute. 10 | 11 | Creating Attributes 12 | -------------------- 13 | 14 | Use :doc:`PUT_Attribute` to create an attribute. If there is an existing attribute 15 | with the same name, it will be overwritten by this request. You can use 16 | :doc:`GET_Attribute` to inquire if the attribute already exists or not. 17 | When creating an attribute, the attribute name, type and shape (for non-scalar 18 | attributes) is included in the request. 19 | 20 | 21 | Reading and Writing Data 22 | ------------------------- 23 | Unlike datasets, an attribute's data can not be 24 | read or written partially. Data can only be written as part of the PUT request. 25 | Reading the data of an attribute is done by :doc:`GET_Attribute`. 26 | 27 | Listing attributes 28 | ------------------ 29 | Use :doc:`GET_Attributes` to get information about all the attributes of a group, 30 | dataset, or committed datatype. 31 | 32 | Deleting Attributes 33 | ------------------- 34 | 35 | Use :doc:`DELETE_Attribute` to delete an attribute. 36 | 37 | List of Operations 38 | ------------------ 39 | 40 | .. toctree:: 41 | :maxdepth: 1 42 | 43 | DELETE_Attribute 44 | GET_Attribute 45 | GET_Attributes 46 | PUT_Attribute 47 | 48 | 49 | 50 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # HDF REST API 2 | 3 | The HDF REST API is an interface to HDF5 data stored on network-based architectures. The HDF REST API has provisions to support CRUD (create, read, update and delete) operations on the full spectrum of HDF5 objects including: groups, links, datasets, attributes, and committed data types. See [RESTful_HDF5.pdf](https://support.hdfgroup.org/archive/support/pubs/papers/index.html) for background on the design principles that guided the development of the RESTful HDF5 interface. 4 | 5 | This repository provides documentation on what operations are supported by the HDF REST API and some guidelines as to how to effectively use these. 6 | 7 | As a REST-based API, different servers can be developed that support the HDF REST API. Some services which have implemented the HDF REST API are: 8 | 9 | * HDF Kita: 10 | * HSDS: 11 | * H5serv: 12 | 13 | Not all implementations support all the REST operations documented here. When a specific operation is not supported in one of the above implementations, it will be noted. 14 | 15 | There are also various packages and libraries that utilize the REST API as a client. These include: 16 | 17 | * [Python SDK - h5pyd](https://github.com/HDFGroup/h5pyd) 18 | * [C/Fortran HDF5 REST VOL](https://bitbucket.hdfgroup.org/users/jhenderson/repos/rest-vol/browse) 19 | * [R SDK - restfulSE](https://github.com/vjcitn/restfulSE) 20 | 21 | 22 | 23 | The following diagram illustrates the various resources and operations of the HDF REST API: 24 | 25 | ![RESTful HDF Diagram](./RESTful_HDF5.png) 26 | -------------------------------------------------------------------------------- /CommonErrorResponses.md: -------------------------------------------------------------------------------- 1 | Common Error Responses 2 | ====================== 3 | 4 | For each request, the HDF REST API returns a standard HTTP status code as described below. In general 2xx codes indicate success, 3xx codes are returned for some form of redirection, 4xx codes are returned for a client error, and 5xx codes are returned for server errors. In addition to the numeric code, the HDF REST API shall return an informational message as part of the response providing further information on the nature of the error. 5 | 6 | > - `200 OK` - The request was completed successfully 7 | > - `201 Created` - The request was fulfilled and a new resource (e.g. group, dataset, attribute was created) 8 | > - `400 Bad Request` - The request was not structured correctly (e.g. a required key was missing). 9 | > - `401 Unauthorization` - User authentication is required, supply an Authentication header with a valid username and password 10 | > - `403 Forbidden` - The requesting user does not have access to the requested resource 11 | > - `404 Not Found` - The requested resource was not found (e.g. `GET /groups/` where <id> was not a valid identifier for a group in the domain). 12 | > - `405 Method Not Allowed` - The HTTP request type was not valid for the given resource (e.g. `PUT /datasets//type`) 13 | > - `409 Conflict` - This error is used with PUT requests where the resources cannot be created because there is an existing resource with the same name (e.g. PUT / where the requested domain is already present). 14 | > - `410 Gone` - The resource requested has been recently deleted. 15 | > - `500 Internal Error` - An unexpected error that indicates some problem occurred on the server. 16 | > - `501 Not Implemented` - The request depends on a feature that is not yet implemented. 17 | 18 | -------------------------------------------------------------------------------- /CommonErrorResponses.rst: -------------------------------------------------------------------------------- 1 | *************************** 2 | Common Error Responses 3 | *************************** 4 | 5 | For each request, the HDF REST API returns a standard HTTP status code as described below. 6 | In general 2xx codes indicate success, 3xx codes are returned for some form of redirection, 7 | 4xx codes are returned for a client error, and 5xx codes are returned for server errors. 8 | In addition to the numeric code, the HDF REST API shall return an informational message as part of 9 | the response providing further information on the nature of the error. 10 | 11 | * ``200 OK`` - The request was completed successfully 12 | * ``201 Created`` - The request was fulfilled and a new resource (e.g. group, dataset, attribute was created) 13 | * ``400 Bad Request`` - The request was not structured correctly (e.g. a required key was missing). 14 | * ``401 Unauthorization`` - User authentication is required, supply an Authentication header with a valid username and password 15 | * ``403 Forbidden`` - The requesting user does not have access to the requested resource 16 | * ``404 Not Found`` - The requested resource was not found (e.g. ``GET /groups/`` where was not a valid identifier for a group in the domain). 17 | * ``405 Method Not Allowed`` - The HTTP request type was not valid for the given resource (e.g. ``PUT /datasets//type``) 18 | * ``409 Conflict`` - This error is used with PUT requests where the resources cannot be created because there is an existing resource with the same name (e.g. PUT / where the requested domain is already present). 19 | * ``410 Gone`` - The resource requested has been recently deleted. 20 | * ``500 Internal Error`` - An unexpected error that indicates some problem occurred on the server. 21 | * ``501 Not Implemented`` - The request depends on a feature that is not yet implemented. 22 | -------------------------------------------------------------------------------- /UsingIteration.md: -------------------------------------------------------------------------------- 1 | Using Iteration 2 | =============== 3 | 4 | There are some operations that may return an arbitrarily large list of results. For example: `GET /groups//attributes` returns all the attributes of the group object with the given id. It's possible (if not common in practice) that the group may contain hundreds or more attributes. 5 | 6 | If you desire to retrieve the list of attributes in batches (say you are developing a user interface that has a "get next page" style button), you can use iteration. 7 | 8 | This is accomplished by adding query parameters to the request that limit the number of items returned and a marker parameter that identifies where the iteration should start off. 9 | 10 | Let's flesh out our example by supposing the group with UUID <id> has 1000 attributes named "a0000", "a0001", and so on. 11 | 12 | If we'd like to retrieve just the first 100 attributes, we can add a limit value to the request like so: 13 | 14 | `GET /groups//attributes?Limit=100` 15 | 16 | Now the response will return attributes "a0000", "a0001", through "a0099". 17 | 18 | To get the next hundred, use the URL-encoded name of the last attribute received as the marker value for the next request: 19 | 20 | `GET /groups//attributes?Limit=100&Marker="a0099"` 21 | 22 | This request will return attributes "a0100", "a0101", through "a0199". 23 | 24 | Repeat this pattern until less than 'Limit' items are returned. This indicates that you've completed the iteration through all elements of the group. 25 | 26 | Iteration is also supported for links in a group, and the groups, datasets, and datatypes collections. 27 | 28 | Related Resources 29 | ----------------- 30 | 31 | - AttrOps/GET\_Attributes 32 | - GroupOps/GET\_Groups 33 | - GroupOps/GET\_Links 34 | - DatasetOps/GET\_Datasets 35 | - DatatypeOps/GET\_Datatypes 36 | 37 | -------------------------------------------------------------------------------- /UsingIteration.rst: -------------------------------------------------------------------------------- 1 | *************** 2 | Using Iteration 3 | *************** 4 | 5 | There are some operations that may return an arbitrarily large list of results. For 6 | example: ``GET /groups//attributes`` returns all the attributes of the 7 | group object with the given id. It's possible (if not common in practice) that the 8 | group may contain hundreds or more attributes. 9 | 10 | If you desire to retrieve the list of attributes in batches (say you are developing a 11 | user interface that has a "get next page" style button), you can use iteration. 12 | 13 | This is accomplished by adding query parameters to the request that limit the number of 14 | items returned and a marker parameter that identifies where the iteration should start 15 | off. 16 | 17 | Let's flesh out our example by supposing the group with UUID has 1000 attributes 18 | named "a0000", "a0001", and so on. 19 | 20 | If we'd like to retrieve just the first 100 attributes, we can add a limit value to the 21 | request like so: 22 | 23 | ``GET /groups//attributes?Limit=100`` 24 | 25 | Now the response will return attributes "a0000", "a0001", through "a0099". 26 | 27 | To get the next hundred, use the URL-encoded name of the last attribute received as the 28 | marker value for the next request: 29 | 30 | ``GET /groups//attributes?Limit=100&Marker="a0099"`` 31 | 32 | This request will return attributes "a0100", "a0101", through "a0199". 33 | 34 | Repeat this pattern until less than 'Limit' items are returned. This indicates that you've 35 | completed the iteration through all elements of the group. 36 | 37 | Iteration is also supported for links in a group, and the groups, datasets, and datatypes 38 | collections. 39 | 40 | Related Resources 41 | ================= 42 | 43 | * :doc:`AttrOps/GET_Attributes` 44 | * :doc:`GroupOps/GET_Groups` 45 | * :doc:`GroupOps/GET_Links` 46 | * :doc:`DatasetOps/GET_Datasets` 47 | * :doc:`DatatypeOps/GET_Datatypes` 48 | 49 | -------------------------------------------------------------------------------- /DomainOps/DELETE_Domain.md: -------------------------------------------------------------------------------- 1 | DELETE Domain 2 | ============= 3 | 4 | Description 5 | ----------- 6 | 7 | The DELETE operation deletes the given domain and all its resources (groups, datasets, attributes, etc.). 8 | 9 | Requests 10 | -------- 11 | 12 | ### Syntax 13 | 14 | ``` sourceCode 15 | DELETE / HTTP/1.1 16 | X-Hdf-domain: DOMAIN 17 | Authorization: 18 | ``` 19 | 20 | ``` sourceCode 21 | DELETE /?domain=DOMAIN HTTP/1.1 22 | Authorization: 23 | ``` 24 | 25 | ### Request Parameters 26 | 27 | This implementation of the operation does not use request parameters. 28 | 29 | ### Request Headers 30 | 31 | This implementation of the operation uses only the request headers that are common to most requests. See ../CommonRequestHeaders 32 | 33 | Responses 34 | --------- 35 | 36 | ### Response Headers 37 | 38 | This implementation of the operation uses only response headers that are common to most responses. See ../CommonResponseHeaders. 39 | 40 | ### Response Elements 41 | 42 | This implementation of the operation does not return any response elements. 43 | 44 | ### Special Errors 45 | 46 | This implementation of the operation does not return special errors. For general information on standard error codes, see ../CommonErrorResponses. 47 | 48 | Examples 49 | -------- 50 | 51 | ### Sample Request 52 | 53 | ``` sourceCode 54 | DELETE / HTTP/1.1 55 | Host: hsdshdflab.hdfgroup.org 56 | X-Hdf-domain: /shared/deleteme.h5 57 | Content-Length: 0 58 | Accept: */* 59 | ``` 60 | 61 | ### Sample cURL command 62 | 63 | ``` sourceCode 64 | $ curl -X DELETE -u username:password --header "X-Hdf-domain: /shared/deleteme.h5" hsdshdflab.hdfgroup.org/ 65 | ``` 66 | 67 | ### Sample Response 68 | 69 | ``` sourceCode 70 | HTTP/1.1 200 OK 71 | Date: Thu, 12 Jul 2018 16:33:54 GMT 72 | Content-Length: 0 73 | Content-Type: application/json 74 | Server: nginx/1.15.0 75 | ``` 76 | 77 | Related Resources 78 | ----------------- 79 | 80 | - GET\_Domain 81 | - PUT\_Domain 82 | 83 | -------------------------------------------------------------------------------- /GroupOps/index.md: -------------------------------------------------------------------------------- 1 | Groups 2 | ====== 3 | 4 | Groups are objects that can be used to organize objects within a domain. Groups contain *links* which can reference other objects (datasets, groups or committed datatypes). There are four different types of links that can be used: 5 | 6 | - hard: A direct link to a group, dataset, or committed datatype object in the domain. 7 | - soft: A symbolic link that gives a path to an object within the domain (object may or may not be present). 8 | - external: A symbolic link to an object that is external to the domain. 9 | - user-defined: A user-defined link (this implementation only provides title and class for user-defined links). 10 | 11 | Groups all have attributes which can be used to store meta-data about the group. 12 | 13 | Creating Groups 14 | --------------- 15 | 16 | Use the POST\_Group operation to create new Groups. Initially the new group will have no links and no attributes. 17 | 18 | Getting information about Groups 19 | -------------------------------- 20 | 21 | Use GET\_Group to get information about a group such as the attribute count, link count and creation and modification times. 22 | 23 | To retrieve the UUIDs of all the groups in a domain, use GET\_Groups. 24 | 25 | To retrieve the links of a group use GET\_Links. Use GET\_Link to get information about a specific link. 26 | 27 | To get a group's attributes, use ../AttrOps/GET\_Attributes. 28 | 29 | Updating Links 30 | -------------- 31 | 32 | To create a hard, soft, or external link, use PUT\_Link. 33 | 34 | To delete a link use DELETE\_Link. 35 | 36 | *Note*: deleting a link doesn't delete the object that it refers to. 37 | 38 | Deleting Groups 39 | --------------- 40 | 41 | Use DELETE\_Group to remove a group. All attributes and links of the group will be deleted. 42 | 43 | *Note:* deleting a group will not delete any objects (datasets or other groups) that the the group's links point to. These objects may become *anonymous*, i.e. they are not referenced by any link, but can still be accessed via a `GET` request with the object UUID. 44 | 45 | List of Operations 46 | ------------------ 47 | -------------------------------------------------------------------------------- /Authorization.md: -------------------------------------------------------------------------------- 1 | Authorization and Authentication 2 | ================================ 3 | 4 | Request Authentication 5 | ---------------------- 6 | 7 | The HDF REST API supports HTTP Basic authentication to authenticate users by comparing an encrypted username and password against a value stored within a password file. 8 | 9 | If neither the requested object (Group, Dataset, or Committed Datatype) nor the object's root group has an Access Control List (ACL), authorization is not required and no authentication string needs to be supplied. See ../AclOps/index) for information on how to use ACL's. 10 | 11 | If the requested object (or object's root group) does have an ACL, authorization may be required (if the object is not publically readable), and if so the requestor will need to provide an Authorization header in the request. If authoriazation is required, but not provided, the server will return an HTTP Status of 401 - Unauthorized. 12 | 13 | If authorization is required (i.e. a 401 response is received), the client should provide an authorization header in the http request which conveys the userid and password. 14 | 15 | The authorization string is constructed as follows: 16 | 17 | > 1. Username and password are combined into a string "username:password". Note that username cannot contain the ":" character 18 | > 2. The resulting string is then encoded using the RFC2045-MIME variant of Base64, except not limited to 76 char/line 19 | > 3. The authorization method and a space i.e. "Basic " is then put before the encoded string 20 | 21 | For example, if the user agent uses 'Aladdin' as the username and 'open sesame' as the password then the field is formed as follows: `Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==`. When passwords are being sent over an open network, SSL connections should be used to avoid "man in the middle attacks". The Base64 encoding is easily reversible and if using plain http there is no assurance that the password will not be compromised. 22 | 23 | If the authorization string is validated, the server will verify the request is authorized as per the object's ACL list. If not authorized a http status 403 - Forbidden will be returned. 24 | -------------------------------------------------------------------------------- /Hypermedia.md: -------------------------------------------------------------------------------- 1 | Hypermedia 2 | ========== 3 | 4 | The HDF REST API supports the REST convention of **HATEOAS** or *Hypermedia as the Engine of Application State*. The idea (see for a full explanation) is that each response includes links to resources related to the requested resource. 5 | 6 | For example, consider the request for a dataset: `GET /datasets/`. The response will be a JSON representation of the dataset describing its type, shape, and other aspects. Related resources to the dataset would include: 7 | 8 | > - the dataset's attributes 9 | > - the dataset's value 10 | > - the dataset collection of the domain 11 | > - the root group of the domain the dataset is in 12 | > - the domain resource 13 | 14 | So the `GET /datasets/` response includes a key `hrefs` that contains a JSON array. Each array element has a key: `href` - the related resource, and a key: `rel` that denotes the type of relation. Example: 15 | 16 | ``` sourceCode 17 | { 18 | "hrefs": [ 19 | {"href": "http://tall.test.hdfgroup.org/datasets/", "rel": "self"}, 20 | {"href": "http://tall.test.hdfgroup.org/groups/", "rel": "root"}, 21 | {"href": "http://tall.test.hdfgroup.org/datasets//attributes", "rel": "attributes"}, 22 | {"href": "http://tall.test.hdfgroup.org/datasets//value", "rel": "data"}, 23 | {"href": "http://tall.test.hdfgroup.org/", "rel": "home"} 24 | ] 25 | } 26 | ``` 27 | 28 | This enables clients to "explore" the API without detailed knowledge of it. 29 | 30 | This is the list of relations used in the HDF REST API: 31 | 32 | > - attributes - the attributes of the resource 33 | > - data - the resource's data (used for datasets) 34 | > - database - the collection of all datasets in the domain 35 | > - groupbase - the collection of all groups in the domain 36 | > - home - the domain the resource is a member of 37 | > - owner - the containing object of this resource (e.g. the group an attribute is a member of) 38 | > - root - the root group of the domain the resource is a member of 39 | > - self - this resource 40 | > - typebase - the collection of all committed types in the domain 41 | 42 | -------------------------------------------------------------------------------- /Authorization.rst: -------------------------------------------------------------------------------- 1 | ********************************* 2 | Authorization and Authentication 3 | ********************************* 4 | 5 | Request Authentication 6 | ----------------------- 7 | The HDF REST API supports HTTP Basic authentication to authenticate users by comparing an encrypted 8 | username and password against a value stored within a password file. 9 | 10 | If neither the requested object (Group, Dataset, or Committed Datatype) nor the object's root group 11 | has an Access Control List (ACL), authorization is not required and no authentication string 12 | needs to be supplied. See :doc:`../AclOps/index`) for information on how to use ACL's. 13 | 14 | If the requested object (or object's root group) does have an ACL, authorization may be required 15 | (if the object is not publically readable), 16 | and if so the requestor will need to provide an Authorization header in the request. If 17 | authoriazation is required, but not provided, the server will return an HTTP Status of 401 - 18 | Unauthorized. 19 | 20 | If authorization is required (i.e. a 401 response is received), the client should provide an authorization header in the 21 | http request which conveys the userid and password. 22 | 23 | The authorization string is constructed as follows: 24 | 25 | 1. Username and password are combined into a string "username:password". Note that username cannot contain the ":" character 26 | 2. The resulting string is then encoded using the RFC2045-MIME variant of Base64, except not limited to 76 char/line 27 | 3. The authorization method and a space i.e. "Basic " is then put before the encoded string 28 | 29 | For example, if the user agent uses 'Aladdin' as the username and 'open sesame' as the password then the field is 30 | formed as follows: 31 | ``Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==``. When passwords are being sent over an open 32 | network, SSL connections should be used to avoid "man in the middle attacks". The Base64 encoding is 33 | easily reversible and if using plain http there is no assurance that the password will not be compromised. 34 | 35 | If the authorization string is validated, the server will verify the request is authorized as 36 | per the object's ACL list. If not authorized a http status 403 - Forbidden will be returned. 37 | 38 | 39 | 40 | -------------------------------------------------------------------------------- /Hypermedia.rst: -------------------------------------------------------------------------------- 1 | ************************* 2 | Hypermedia 3 | ************************* 4 | 5 | The HDF REST API supports the REST convention of **HATEOAS** or *Hypermedia as the Engine of 6 | Application State*. The idea (see http://en.wikipedia.org/wiki/HATEOS for a full 7 | explanation) is that each response includes links to resources related to 8 | the requested resource. 9 | 10 | For example, consider the request for a dataset: ``GET /datasets/``. The response 11 | will be a JSON representation of the dataset describing its type, shape, and other 12 | aspects. Related resources to the dataset would include: 13 | 14 | * the dataset's attributes 15 | * the dataset's value 16 | * the dataset collection of the domain 17 | * the root group of the domain the dataset is in 18 | * the domain resource 19 | 20 | So the ``GET /datasets/`` response includes a key ``hrefs`` that contains 21 | a JSON array. Each array element has a key: ``href`` - the related resource, and a key: 22 | ``rel`` that denotes the type of relation. Example: 23 | 24 | .. code-block:: json 25 | 26 | { 27 | "hrefs": [ 28 | {"href": "http://tall.test.hdfgroup.org/datasets/", "rel": "self"}, 29 | {"href": "http://tall.test.hdfgroup.org/groups/", "rel": "root"}, 30 | {"href": "http://tall.test.hdfgroup.org/datasets//attributes", "rel": "attributes"}, 31 | {"href": "http://tall.test.hdfgroup.org/datasets//value", "rel": "data"}, 32 | {"href": "http://tall.test.hdfgroup.org/", "rel": "home"} 33 | ] 34 | } 35 | 36 | This enables clients to "explore" the API without detailed knowledge of it. 37 | 38 | This is the list of relations used in the HDF REST API: 39 | 40 | * attributes - the attributes of the resource 41 | * data - the resource's data (used for datasets) 42 | * database - the collection of all datasets in the domain 43 | * groupbase - the collection of all groups in the domain 44 | * home - the domain the resource is a member of 45 | * owner - the containing object of this resource (e.g. the group an attribute is a member of) 46 | * root - the root group of the domain the resource is a member of 47 | * self - this resource 48 | * typebase - the collection of all committed types in the domain 49 | -------------------------------------------------------------------------------- /DomainOps/DELETE_Domain.rst: -------------------------------------------------------------------------------- 1 | ********************************************** 2 | DELETE Domain 3 | ********************************************** 4 | 5 | Description 6 | =========== 7 | The DELETE operation deletes the given domain and 8 | all its resources (groups, datasets, attributes, etc.). 9 | 10 | Requests 11 | ======== 12 | 13 | Syntax 14 | ------ 15 | .. code-block:: http 16 | 17 | DELETE / HTTP/1.1 18 | X-Hdf-domain: DOMAIN 19 | Authorization: 20 | 21 | .. code-block:: http 22 | 23 | DELETE /?domain=DOMAIN HTTP/1.1 24 | Authorization: 25 | 26 | Request Parameters 27 | ------------------ 28 | This implementation of the operation does not use request parameters. 29 | 30 | Request Headers 31 | --------------- 32 | This implementation of the operation uses only the request headers that are common 33 | to most requests. See :doc:`../CommonRequestHeaders` 34 | 35 | Responses 36 | ========= 37 | 38 | Response Headers 39 | ---------------- 40 | 41 | This implementation of the operation uses only response headers that are common to 42 | most responses. See :doc:`../CommonResponseHeaders`. 43 | 44 | Response Elements 45 | ----------------- 46 | 47 | This implementation of the operation does not return any response elements. 48 | 49 | 50 | Special Errors 51 | -------------- 52 | 53 | This implementation of the operation does not return special errors. For general 54 | information on standard error codes, see :doc:`../CommonErrorResponses`. 55 | 56 | Examples 57 | ======== 58 | 59 | Sample Request 60 | -------------- 61 | 62 | .. code-block:: http 63 | 64 | DELETE / HTTP/1.1 65 | Host: hsdshdflab.hdfgroup.org 66 | X-Hdf-domain: /shared/deleteme.h5 67 | Content-Length: 0 68 | Accept: */* 69 | 70 | Sample cURL command 71 | ------------------- 72 | 73 | .. code-block:: bash 74 | 75 | $ curl -X DELETE -u username:password --header "X-Hdf-domain: /shared/deleteme.h5" hsdshdflab.hdfgroup.org/ 76 | 77 | Sample Response 78 | --------------- 79 | 80 | .. code-block:: http 81 | 82 | HTTP/1.1 200 OK 83 | Date: Thu, 12 Jul 2018 16:33:54 GMT 84 | Content-Length: 0 85 | Content-Type: application/json 86 | Server: nginx/1.15.0 87 | 88 | 89 | Related Resources 90 | ================= 91 | 92 | * :doc:`GET_Domain` 93 | * :doc:`PUT_Domain` 94 | 95 | 96 | -------------------------------------------------------------------------------- /DatatypeOps/DELETE_Datatype.md: -------------------------------------------------------------------------------- 1 | DELETE Datatype 2 | =============== 3 | 4 | Description 5 | ----------- 6 | 7 | The implementation of the DELETE operation deletes the committed datatype 8 | named in the URI. All attributes of the datatype will also be deleted. 9 | 10 | Requests 11 | -------- 12 | 13 | ### Syntax 14 | 15 | ``` sourceCode 16 | DELETE /datatypes/ HTTP/1.1 17 | X-Hdf-domain: DOMAIN 18 | Authorization: 19 | ``` 20 | 21 | ``` sourceCode 22 | DELETE /datatypes/?domain=DOMAIN HTTP/1.1 23 | Authorization: 24 | ``` 25 | 26 | *<id>* is the UUID of the datatype to be deleted. 27 | 28 | ### Request Parameters 29 | 30 | This implementation of the operation does not use request parameters. 31 | 32 | ### Request Headers 33 | 34 | This implementation of the operation uses only the request headers that are common to most requests. See ../CommonRequestHeaders 35 | 36 | Responses 37 | --------- 38 | 39 | ### Response Headers 40 | 41 | This implementation of the operation uses only response headers that are common to most responses. See ../CommonResponseHeaders. 42 | 43 | ### Response Elements 44 | 45 | This implementation of the operation does not return any response elements. 46 | 47 | ### Special Errors 48 | 49 | This implementation of the operation does not return special errors. For general information on standard error codes, see ../CommonErrorResponses. 50 | 51 | Examples 52 | -------- 53 | 54 | ### Sample Request 55 | 56 | ``` sourceCode 57 | DELETE /datatypes/t-6b0bdf9a-86b2-11e8-89f2-0242ac120009 HTTP/1.1 58 | Host: hsdshdflab.hdfgroup.org 59 | X-Hdf-domain: /shared/tall.h5 60 | Content-Length: 0 61 | Accept: */* 62 | Accept-Encoding: gzip, deflate 63 | ``` 64 | 65 | ### Sample cURL command 66 | 67 | ``` sourceCode 68 | $ curl -X DELETE -u username:password --header "X-Hdf-domain: /shared/tall.h5" hsdshdflab.hdfgroup.org/datatypes/t-6b0bdf9a-86b2-11e8-89f2-0242ac120009 69 | ``` 70 | 71 | ### Sample Response 72 | 73 | ``` sourceCode 74 | HTTP/1.1 200 OK 75 | Date: Fri, 13 Jul 2018 15:49:44 GMT 76 | Content-Type: application/json 77 | Server: nginx/1.15.0 78 | ``` 79 | 80 | Related Resources 81 | ----------------- 82 | 83 | - ../AttrOps/GET\_Attributes 84 | - GET\_Datatype 85 | - GET\_Datatypes 86 | - POST\_Datatype 87 | - ../DatasetOps/POST\_Dataset 88 | - ../AttrOps/PUT\_Attribute 89 | 90 | -------------------------------------------------------------------------------- /GroupOps/DELETE_Group.md: -------------------------------------------------------------------------------- 1 | DELETE Group 2 | ============ 3 | 4 | Description 5 | ----------- 6 | 7 | The implementation of the DELETE operation deletes the group with the UUID given in the URI. All attributes and links of the group will also be deleted. In addition, any links from other groups **TO** the deleted group will be removed. 8 | 9 | *Note:* Groups, datatypes, and datasets that are referenced by the group's links will **not** be deleted. Use the DELETE operation for those objects to remove them. 10 | 11 | Requests 12 | -------- 13 | 14 | ### Syntax 15 | 16 | ``` sourceCode 17 | DELETE /groups/ HTTP/1.1 18 | X-Hdf-domain: DOMAIN 19 | Authorization: 20 | ``` 21 | 22 | ``` sourceCode 23 | DELETE /groups/?domain=DOMAIN HTTP/1.1 24 | Authorization: 25 | ``` 26 | 27 | *<id>* is the UUID of the group to be deleted. 28 | 29 | ### Request Parameters 30 | 31 | This implementation of the operation does not use request parameters. 32 | 33 | ### Request Headers 34 | 35 | This implementation of the operation uses only the request headers that are common to most requests. See ../CommonRequestHeaders 36 | 37 | Responses 38 | --------- 39 | 40 | ### Response Headers 41 | 42 | This implementation of the operation uses only response headers that are common to most responses. See ../CommonResponseHeaders. 43 | 44 | ### Response Elements 45 | 46 | This implementation of the operation does not return any response elements. 47 | 48 | ### Special Errors 49 | 50 | This implementation of the operation does not return special errors. For general information on standard error codes, see ../CommonErrorResponses. 51 | 52 | Examples 53 | -------- 54 | 55 | ### Sample Request 56 | 57 | ``` sourceCode 58 | DELETE /groups/g-76de767c-8606-11e8-9cc2-0242ac120008 HTTP/1.1 59 | Host: hsdshdflab.hdfgroup.org 60 | X-Hdf-domain: /shared/tall.h5 61 | Authorization: authorization_string 62 | ``` 63 | 64 | ### Sample cURL command 65 | 66 | ``` sourceCode 67 | $ curl -X DELETE -u username:password --header "X-Hdf-domain: /shared/tall.h5" hsdshdflab.hdfgroup.org/groups/g-76de767c-8606-11e8-9cc2-0242ac120008 68 | ``` 69 | 70 | ### Sample Response 71 | 72 | ``` sourceCode 73 | HTTP/1.1 200 OK 74 | Date: Thu, 12 Jul 2018 19:05:43 GMT 75 | Content-Type: application/json 76 | Server: nginx/1.15.0 77 | ``` 78 | 79 | Related Resources 80 | ----------------- 81 | 82 | - POST\_Group 83 | - GET\_Group 84 | 85 | -------------------------------------------------------------------------------- /GroupOps/index.rst: -------------------------------------------------------------------------------- 1 | #################### 2 | Groups 3 | #################### 4 | 5 | Groups are objects that can be used to organize objects within a domain. Groups contain 6 | *links* which can reference other objects (datasets, groups or committed datatypes). 7 | There are four different types of links that can be used: 8 | 9 | * hard: A direct link to a group, dataset, or committed datatype object in the domain. 10 | * soft: A symbolic link that gives a path to an object within the domain (object may or may not be present). 11 | * external: A symbolic link to an object that is external to the domain. 12 | * user-defined: A user-defined link (this implementation only provides title and class for user-defined links). 13 | 14 | Groups all have attributes which can be used to store meta-data about the group. 15 | 16 | Creating Groups 17 | --------------- 18 | 19 | Use the :doc:`POST_Group` operation to create new Groups. Initially the new group will have no 20 | links and no attributes. 21 | 22 | 23 | Getting information about Groups 24 | -------------------------------- 25 | 26 | Use :doc:`GET_Group` to get information about a group such as the attribute count, link count 27 | and creation and modification times. 28 | 29 | To retrieve the UUIDs of all the groups in a domain, use :doc:`GET_Groups`. 30 | 31 | To retrieve the links of a group use :doc:`GET_Links`. Use :doc:`GET_Link` to get 32 | information about a specific link. 33 | 34 | To get a group's attributes, use :doc:`../AttrOps/GET_Attributes`. 35 | 36 | Updating Links 37 | --------------- 38 | 39 | To create a hard, soft, or external link, use :doc:`PUT_Link`. 40 | 41 | To delete a link use :doc:`DELETE_Link`. 42 | 43 | *Note*: deleting a link doesn't delete the object that it refers to. 44 | 45 | 46 | Deleting Groups 47 | --------------- 48 | Use :doc:`DELETE_Group` to remove a group. All attributes and links of the group 49 | will be deleted. 50 | 51 | *Note:* deleting a group will not delete any objects (datasets or other groups) that the 52 | the group's links point to. These objects may become *anonymous*, i.e. they are not 53 | referenced by any link, but can still be accessed via a ``GET`` request with the object 54 | UUID. 55 | 56 | List of Operations 57 | ------------------ 58 | 59 | .. toctree:: 60 | :maxdepth: 1 61 | 62 | DELETE_Group 63 | DELETE_Link 64 | GET_Group 65 | GET_Groups 66 | GET_Link 67 | GET_Links 68 | POST_Group 69 | PUT_Link 70 | 71 | 72 | -------------------------------------------------------------------------------- /DatasetOps/DELETE_Dataset.md: -------------------------------------------------------------------------------- 1 | DELETE Dataset 2 | ============== 3 | 4 | Description 5 | ----------- 6 | 7 | The implementation of the DELETE operation deletes the dataset named in the URI. All attributes and links of the dataset will also be deleted. In addition any links from other groups to the deleted group will be removed. 8 | 9 | Requests 10 | -------- 11 | 12 | ### Syntax 13 | 14 | ``` sourceCode 15 | DELETE /datasets/ HTTP/1.1 16 | Host: DOMAIN 17 | Authorization: 18 | ``` 19 | 20 | *<id>* is the UUID of the requested dataset to be deleted. 21 | 22 | ### Request Parameters 23 | 24 | This implementation of the operation does not use request parameters. 25 | 26 | ### Request Headers 27 | 28 | This implementation of the operation uses only the request headers that are common to most requests. See ../CommonRequestHeaders 29 | 30 | Responses 31 | --------- 32 | 33 | ### Response Headers 34 | 35 | This implementation of the operation uses only response headers that are common to most responses. See ../CommonResponseHeaders. 36 | 37 | ### Response Elements 38 | 39 | On success, a JSON response will be returned with the following elements: 40 | 41 | #### hrefs 42 | 43 | An array of links to related resources. See ../Hypermedia. 44 | 45 | ### Special Errors 46 | 47 | This implementation of the operation does not return special errors. For general information on standard error codes, see ../CommonErrorResponses. 48 | 49 | Examples 50 | -------- 51 | 52 | ### Sample Request 53 | 54 | ``` sourceCode 55 | DELETE /datasets/289bb654-a2c6-11e4-97d8-3c15c2da029e HTTP/1.1 56 | Content-Length: 0 57 | User-Agent: python-requests/2.3.0 CPython/2.7.8 Darwin/14.0.0 58 | host: tall_dset112_deleted.test.hdfgroup.org 59 | Accept: */* 60 | Accept-Encoding: gzip, deflate 61 | ``` 62 | 63 | ### Sample Response 64 | 65 | ``` sourceCode 66 | HTTP/1.1 200 OK 67 | Date: Fri, 23 Jan 2015 06:07:49 GMT 68 | Content-Length: 287 69 | Content-Type: application/json 70 | Server: TornadoServer/3.2.2 71 | ``` 72 | 73 | ``` sourceCode 74 | { 75 | "hrefs": [ 76 | {"href": "http://tall_dset112_deleted.test.hdfgroup.org/datasets", "rel": "self"}, 77 | {"href": "http://tall_dset112_deleted.test.hdfgroup.org/groups/289b4873-a2c6-11e4-adfb-3c15c2da029e", "rel": "root"}, 78 | {"href": "http://tall_dset112_deleted.test.hdfgroup.org/", "rel": "home"} 79 | ] 80 | } 81 | ``` 82 | 83 | Related Resources 84 | ----------------- 85 | 86 | - GET\_Datasets 87 | - GET\_Dataset 88 | - POST\_Dataset 89 | 90 | -------------------------------------------------------------------------------- /DomainOps/index.md: -------------------------------------------------------------------------------- 1 | Domains 2 | ======= 3 | 4 | In the HDF REST API, domains are containers for a related collection of resources, similar to a file in the traditional HDF5 library. In the HDF Kita implementation of the HDF REST API, domains *are* files, but in general the HDF REST API supports alternative implementations (e.g. data that is stored in a database). Most operations of the service act on a domain resource that is provided in the *X-Hdf-domain* http header or (alternatively) the domain query parameter. 5 | 6 | Mapping of file paths to domain names 7 | ------------------------------------- 8 | 9 | To convert a file path to a domain name: 10 | 11 | 1. Remove the extension 12 | 2. Determine the path relative to the data directory 13 | 3. Replace '/' with '.' 14 | 4. Reverse the path 15 | 5. Add the domain suffix (using the domain config value) 16 | 17 | As an example, consider a server installation where the data directory is '/data' and an HDF5 "file" is located at `/data/myfolder/an_hdf_file.h5` and `hdfgroup.org` is the base domain. The above sequence of steps would look like the following: 18 | 19 | 1. /data/myfolder/an\_hdf\_file 20 | 2. myfolder/an\_hdf\_file 21 | 3. myfolder.an\_hdf\_file 22 | 4. an\_hdf\_file.myfolder 23 | 5. an\_hdf\_file.myfolder.hdfgroup.org 24 | 25 | The final expression is what should be used in the Host field for any request that accesses that file. 26 | 27 | For path names that include non-alphanumeric characters, replace any such characters with the string '%XX' where XX is the hexadecimal value of the character. For example: 28 | 29 | `this.file.has.dots.h5` 30 | 31 | becomes: 32 | 33 | `this%2Efile%2Ehase%2Edots` 34 | 35 | Creating Domains 36 | ---------------- 37 | 38 | Use PUT\_Domain to create a domain. The domain name must follow DNS conventions (e.g. two consecutive "dots" are not allowed). After creation, the domain will contain just one resource, the root group. 39 | 40 | Getting Information about Domains 41 | --------------------------------- 42 | 43 | Use GET\_Domain to retrieve information about a specific domain (specified in the Host header), including the UUID of the domain's root group. If the Host value is not supplied, the service returns information in the auto-generated Table of Contents (TOC) that provides information on domains that are available. 44 | 45 | Deleting Domains 46 | ---------------- 47 | 48 | Use DELETE\_Domain to delete a domain. All resources within the domain will be deleted! 49 | 50 | The TOC domain cannot be deleted. 51 | 52 | List of Operations 53 | ------------------ 54 | -------------------------------------------------------------------------------- /DatasetOps/POST_Value.md: -------------------------------------------------------------------------------- 1 | POST Value 2 | ========== 3 | 4 | Description 5 | ----------- 6 | 7 | Gets values of a dataset for a given point selection (provided in the body of the request). 8 | 9 | Requests 10 | -------- 11 | 12 | ### Syntax 13 | 14 | ``` sourceCode 15 | POST /datasets//value HTTP/1.1 16 | Host: DOMAIN 17 | Authorization: 18 | ``` 19 | 20 | *<id>* is the UUID of the requested dataset t 21 | 22 | ### Request Parameters 23 | 24 | This implementation of the operation does not use request parameters. 25 | 26 | ### Request Headers 27 | 28 | This implementation of the operation uses only the request headers that are common to most requests. See ../CommonRequestHeaders 29 | 30 | ### Request Body 31 | 32 | The request body should be a JSON object with the following key: 33 | 34 | #### points 35 | 36 | An array of points defining the selection. Each point can either be an integer (if the dataset has just one dimension), or an array where the length of the array is equal to the number of dimensions of the dataset. 37 | 38 | Responses 39 | --------- 40 | 41 | ### Response Headers 42 | 43 | This implementation of the operation uses only response headers that are common to most responses. See ../CommonResponseHeaders. 44 | 45 | ### Response Elements 46 | 47 | On success, a JSON response will be returned with the following elements: 48 | 49 | #### value 50 | 51 | An array of values where the length of the array is equal to the number of points in the request. Each value will be a string, integer, or JSON object consistent with the dataset type (e.g. a compound type). 52 | 53 | ### Special Errors 54 | 55 | This implementation of the operation does not return special errors. For general information on standard error codes, see ../CommonErrorResponses. 56 | 57 | Examples 58 | -------- 59 | 60 | ### Sample Request 61 | 62 | ``` sourceCode 63 | POST /datasets/4e83ad1c-ab6e-11e4-babb-3c15c2da029e/value HTTP/1.1 64 | Content-Length: 92 65 | User-Agent: python-requests/2.3.0 CPython/2.7.8 Darwin/14.0.0 66 | host: tall.test.hdfgroup.org 67 | Accept: */* 68 | Accept-Encoding: gzip, deflate 69 | ``` 70 | 71 | ``` sourceCode 72 | { 73 | "points": [19, 17, 13, 11, 7, 5, 3, 2] 74 | } 75 | ``` 76 | 77 | ### Sample Response 78 | 79 | ``` sourceCode 80 | HTTP/1.1 200 OK 81 | Date: Tue, 03 Feb 2015 06:31:38 GMT 82 | Content-Length: 47 83 | Content-Type: application/json 84 | Server: TornadoServer/3.2.2 85 | ``` 86 | 87 | ``` sourceCode 88 | { 89 | "value": [0, 1, 4, 9, 16, 25, 36, 49, 64, 81] 90 | } 91 | ``` 92 | 93 | Related Resources 94 | ----------------- 95 | 96 | - GET\_Dataset 97 | - GET\_Value 98 | - PUT\_Value 99 | 100 | -------------------------------------------------------------------------------- /GroupOps/DELETE_Group.rst: -------------------------------------------------------------------------------- 1 | ********************************************** 2 | DELETE Group 3 | ********************************************** 4 | 5 | Description 6 | =========== 7 | The implementation of the DELETE operation deletes the group with the UUID given in the 8 | URI. All attributes and links of the group will also be deleted. In addition, any 9 | links from other groups **TO** the deleted group will be removed. 10 | 11 | *Note:* Groups, datatypes, and datasets that are referenced by the group's links will 12 | **not** be deleted. Use the DELETE operation for those objects to remove them. 13 | 14 | Requests 15 | ======== 16 | 17 | Syntax 18 | ------ 19 | 20 | .. code-block:: http 21 | 22 | DELETE /groups/ HTTP/1.1 23 | X-Hdf-domain: DOMAIN 24 | Authorization: 25 | 26 | .. code-block:: http 27 | 28 | DELETE /groups/?domain=DOMAIN HTTP/1.1 29 | Authorization: 30 | 31 | ** is the UUID of the group to be deleted. 32 | 33 | Request Parameters 34 | ------------------ 35 | This implementation of the operation does not use request parameters. 36 | 37 | Request Headers 38 | --------------- 39 | This implementation of the operation uses only the request headers that are common 40 | to most requests. See :doc:`../CommonRequestHeaders` 41 | 42 | Responses 43 | ========= 44 | 45 | Response Headers 46 | ---------------- 47 | 48 | This implementation of the operation uses only response headers that are common to 49 | most responses. See :doc:`../CommonResponseHeaders`. 50 | 51 | Response Elements 52 | ----------------- 53 | 54 | This implementation of the operation does not return any response elements. 55 | 56 | Special Errors 57 | -------------- 58 | 59 | This implementation of the operation does not return special errors. For general 60 | information on standard error codes, see :doc:`../CommonErrorResponses`. 61 | 62 | Examples 63 | ======== 64 | 65 | Sample Request 66 | -------------- 67 | 68 | .. code-block:: http 69 | 70 | DELETE /groups/g-76de767c-8606-11e8-9cc2-0242ac120008 HTTP/1.1 71 | Host: hsdshdflab.hdfgroup.org 72 | X-Hdf-domain: /shared/tall.h5 73 | Authorization: authorization_string 74 | 75 | Sample cURL command 76 | ------------------- 77 | 78 | .. code-block:: bash 79 | 80 | $ curl -X DELETE -u username:password --header "X-Hdf-domain: /shared/tall.h5" hsdshdflab.hdfgroup.org/groups/g-76de767c-8606-11e8-9cc2-0242ac120008 81 | 82 | Sample Response 83 | --------------- 84 | 85 | .. code-block:: http 86 | 87 | HTTP/1.1 200 OK 88 | Date: Thu, 12 Jul 2018 19:05:43 GMT 89 | Content-Type: application/json 90 | Server: nginx/1.15.0 91 | 92 | Related Resources 93 | ================= 94 | 95 | * :doc:`POST_Group` 96 | * :doc:`GET_Group` 97 | 98 | 99 | -------------------------------------------------------------------------------- /DomainOps/index.rst: -------------------------------------------------------------------------------- 1 | ####################### 2 | Domains 3 | ####################### 4 | 5 | In the HDF REST API, domains are containers for a related collection of resources, similar to a 6 | file in the traditional HDF5 library. In the HDF Kita implementation of the HDF REST API, 7 | domains *are* files, but in general the HDF REST API supports alternative implementations 8 | (e.g. data that is stored in a database). 9 | Most operations of the service act on a domain resource that is provided in 10 | the *X-Hdf-domain* http header or (alternatively) the domain query parameter. 11 | 12 | Mapping of file paths to domain names 13 | ------------------------------------- 14 | 15 | To convert a file path to a domain name: 16 | 17 | #. Remove the extension 18 | #. Determine the path relative to the data directory 19 | #. Replace '/' with '.' 20 | #. Reverse the path 21 | #. Add the domain suffix (using the domain config value) 22 | 23 | As an example, consider a server installation where the data directory is '/data' 24 | and an HDF5 "file" is located at ``/data/myfolder/an_hdf_file.h5`` and ``hdfgroup.org`` 25 | is the base domain. The above sequence of steps would look like the following: 26 | 27 | #. /data/myfolder/an_hdf_file 28 | #. myfolder/an_hdf_file 29 | #. myfolder.an_hdf_file 30 | #. an_hdf_file.myfolder 31 | #. an_hdf_file.myfolder.hdfgroup.org 32 | 33 | The final expression is what should be used in the Host field for any request that accesses 34 | that file. 35 | 36 | For path names that include non-alphanumeric characters, replace any such characters with 37 | the string '%XX' where XX is the hexadecimal value of the character. For example: 38 | 39 | ``this.file.has.dots.h5`` 40 | 41 | becomes: 42 | 43 | ``this%2Efile%2Ehase%2Edots`` 44 | 45 | 46 | Creating Domains 47 | ---------------- 48 | Use :doc:`PUT_Domain` to create a domain. The domain name must follow DNS conventions 49 | (e.g. two consecutive "dots" are not allowed). After creation, the domain will contain 50 | just one resource, the root group. 51 | 52 | Getting Information about Domains 53 | --------------------------------- 54 | 55 | Use :doc:`GET_Domain` to retrieve information about a specific domain (specified in the Host 56 | header), including the UUID of the domain's root group. If the Host value is not supplied, 57 | the service returns information in the auto-generated Table of Contents (TOC) that provides 58 | information on domains that are available. 59 | 60 | Deleting Domains 61 | ---------------- 62 | Use :doc:`DELETE_Domain` to delete a domain. All resources within the domain will be 63 | deleted! 64 | 65 | The TOC domain cannot be deleted. 66 | 67 | List of Operations 68 | ------------------ 69 | 70 | .. toctree:: 71 | :maxdepth: 1 72 | 73 | DELETE_Domain 74 | GET_Domain 75 | PUT_Domain 76 | 77 | 78 | -------------------------------------------------------------------------------- /DatatypeOps/DELETE_Datatype.rst: -------------------------------------------------------------------------------- 1 | ********************************************** 2 | DELETE Datatype 3 | ********************************************** 4 | 5 | Description 6 | =========== 7 | The implementation of the DELETE operation deletes the committed datatype 8 | named in the URI. All attributes of the datatype will also be deleted. 9 | 10 | Requests 11 | ======== 12 | 13 | Syntax 14 | ------ 15 | .. code-block:: http 16 | 17 | DELETE /datatypes/ HTTP/1.1 18 | X-Hdf-domain: DOMAIN 19 | Authorization: 20 | 21 | .. code-block:: http 22 | 23 | DELETE /datatypes/?domain=DOMAIN HTTP/1.1 24 | Authorization: 25 | 26 | ** is the UUID of the datatype to be deleted. 27 | 28 | Request Parameters 29 | ------------------ 30 | This implementation of the operation does not use request parameters. 31 | 32 | Request Headers 33 | --------------- 34 | This implementation of the operation uses only the request headers that are common 35 | to most requests. See :doc:`../CommonRequestHeaders` 36 | 37 | Responses 38 | ========= 39 | 40 | Response Headers 41 | ---------------- 42 | 43 | This implementation of the operation uses only response headers that are common to 44 | most responses. See :doc:`../CommonResponseHeaders`. 45 | 46 | Response Elements 47 | ----------------- 48 | 49 | This implementation of the operation does not return any response elements. 50 | 51 | Special Errors 52 | -------------- 53 | 54 | This implementation of the operation does not return special errors. For general 55 | information on standard error codes, see :doc:`../CommonErrorResponses`. 56 | 57 | Examples 58 | ======== 59 | 60 | Sample Request 61 | -------------- 62 | 63 | .. code-block:: http 64 | 65 | DELETE /datatypes/t-6b0bdf9a-86b2-11e8-89f2-0242ac120009 HTTP/1.1 66 | Host: hsdshdflab.hdfgroup.org 67 | X-Hdf-domain: /shared/tall.h5 68 | Content-Length: 0 69 | Accept: */* 70 | Accept-Encoding: gzip, deflate 71 | 72 | Sample cURL command 73 | ------------------- 74 | 75 | .. code-block:: bash 76 | 77 | $ curl -X DELETE -u username:password --header "X-Hdf-domain: /shared/tall.h5" hsdshdflab.hdfgroup.org/datatypes/t-6b0bdf9a-86b2-11e8-89f2-0242ac120009 78 | 79 | Sample Response 80 | --------------- 81 | 82 | .. code-block:: http 83 | 84 | HTTP/1.1 200 OK 85 | Date: Fri, 13 Jul 2018 15:49:44 GMT 86 | Content-Type: application/json 87 | Server: nginx/1.15.0 88 | 89 | Related Resources 90 | ================= 91 | 92 | * :doc:`../AttrOps/GET_Attributes` 93 | * :doc:`GET_Datatype` 94 | * :doc:`GET_Datatypes` 95 | * :doc:`POST_Datatype` 96 | * :doc:`../DatasetOps/POST_Dataset` 97 | * :doc:`../AttrOps/PUT_Attribute` 98 | 99 | 100 | -------------------------------------------------------------------------------- /GroupOps/DELETE_Link.md: -------------------------------------------------------------------------------- 1 | DELETE Link 2 | =========== 3 | 4 | Description 5 | ----------- 6 | 7 | The implementation of the DELETE operation deletes the link named in the URI. 8 | 9 | Groups, datatypes, and datasets that are referenced by the link will **not** be deleted. To delete groups, datatypes or datasets, use the appropriate DELETE operation for those objects. 10 | 11 | Requests 12 | -------- 13 | 14 | ### Syntax 15 | 16 | ``` sourceCode 17 | DELETE /groups//links/ HTTP/1.1 18 | X-Hdf-domain: DOMAIN 19 | Authorization: 20 | ``` 21 | 22 | ``` sourceCode 23 | DELETE /groups//links/?domain=DOMAIN HTTP/1.1 24 | Authorization: 25 | ``` 26 | 27 | - *<id>* is the UUID of the group the link is a member of. 28 | - *<name>* is the URL-encoded name of the link. 29 | 30 | ### Request Parameters 31 | 32 | This implementation of the operation does not use request parameters. 33 | 34 | ### Request Headers 35 | 36 | This implementation of the operation uses only the request headers that are common to most requests. See ../CommonRequestHeaders 37 | 38 | Responses 39 | --------- 40 | 41 | ### Response Headers 42 | 43 | This implementation of the operation uses only response headers that are common to most responses. See ../CommonResponseHeaders. 44 | 45 | ### Response Elements 46 | 47 | On success, a JSON response will be returned with the following elements: 48 | 49 | #### hrefs 50 | 51 | An array of links to related resources. See ../Hypermedia. 52 | 53 | ### Special Errors 54 | 55 | An attempt to delete the root group will return 403 - Forbidden. For general information on standard error codes, see ../CommonErrorResponses. 56 | 57 | Examples 58 | -------- 59 | 60 | ### Sample Request 61 | 62 | ``` sourceCode 63 | DELETE /groups/g-b116b6f0-85e9-11e8-9cc2-0242ac120008/links/deleteme HTTP/1.1 64 | Host: hsdshdflab.hdfgroup.org 65 | X-Hdf-domain: /shared/tall.h5 66 | Content-Length: 0 67 | Accept: */* 68 | Accept-Encoding: gzip, deflate 69 | ``` 70 | 71 | ### Sample cURL command 72 | 73 | ``` sourceCode 74 | $ curl -X DELETE -u username:password --header "X-Hdf-domain: /shared/tall.h5" hsdshdflab.hdfgroup.org/groups/g-b116b6f0-85e9-11e8-9cc2-0242ac120008/links/deleteme 75 | ``` 76 | 77 | ### Sample Response 78 | 79 | ``` sourceCode 80 | HTTP/1.1 200 OK 81 | Date: Thu, 12 Jul 2018 19:45:54 GMT 82 | Content-Length: 12 83 | Content-Type: application/json 84 | Server: nginx/1.15.0 85 | ``` 86 | 87 | ``` sourceCode 88 | {"href": []} 89 | ``` 90 | 91 | Related Resources 92 | ----------------- 93 | 94 | - ../DatasetOps/DELETE\_Dataset 95 | - ../DatatypeOps/DELETE\_Datatype 96 | - DELETE\_Group 97 | - GET\_Link 98 | - GET\_Groups 99 | - POST\_Group 100 | 101 | -------------------------------------------------------------------------------- /DatasetOps/DELETE_Dataset.rst: -------------------------------------------------------------------------------- 1 | ********************************************** 2 | DELETE Dataset 3 | ********************************************** 4 | 5 | Description 6 | =========== 7 | The implementation of the DELETE operation deletes the dataset named in the URI. All 8 | attributes and links of the dataset will also be deleted. In addition any 9 | links from other groups to the deleted group will be removed. 10 | 11 | Requests 12 | ======== 13 | 14 | Syntax 15 | ------ 16 | .. code-block:: http 17 | 18 | DELETE /datasets/ HTTP/1.1 19 | Host: DOMAIN 20 | Authorization: 21 | 22 | ** is the UUID of the requested dataset to be deleted. 23 | 24 | Request Parameters 25 | ------------------ 26 | This implementation of the operation does not use request parameters. 27 | 28 | Request Headers 29 | --------------- 30 | This implementation of the operation uses only the request headers that are common 31 | to most requests. See :doc:`../CommonRequestHeaders` 32 | 33 | Responses 34 | ========= 35 | 36 | Response Headers 37 | ---------------- 38 | 39 | This implementation of the operation uses only response headers that are common to 40 | most responses. See :doc:`../CommonResponseHeaders`. 41 | 42 | Response Elements 43 | ----------------- 44 | 45 | On success, a JSON response will be returned with the following elements: 46 | 47 | hrefs 48 | ^^^^^ 49 | An array of links to related resources. See :doc:`../Hypermedia`. 50 | 51 | Special Errors 52 | -------------- 53 | 54 | This implementation of the operation does not return special errors. For general 55 | information on standard error codes, see :doc:`../CommonErrorResponses`. 56 | 57 | Examples 58 | ======== 59 | 60 | Sample Request 61 | -------------- 62 | 63 | .. code-block:: http 64 | 65 | DELETE /datasets/289bb654-a2c6-11e4-97d8-3c15c2da029e HTTP/1.1 66 | Content-Length: 0 67 | User-Agent: python-requests/2.3.0 CPython/2.7.8 Darwin/14.0.0 68 | host: tall_dset112_deleted.test.hdfgroup.org 69 | Accept: */* 70 | Accept-Encoding: gzip, deflate 71 | 72 | Sample Response 73 | --------------- 74 | 75 | .. code-block:: http 76 | 77 | HTTP/1.1 200 OK 78 | Date: Fri, 23 Jan 2015 06:07:49 GMT 79 | Content-Length: 287 80 | Content-Type: application/json 81 | Server: TornadoServer/3.2.2 82 | 83 | .. code-block:: json 84 | 85 | { 86 | "hrefs": [ 87 | {"href": "http://tall_dset112_deleted.test.hdfgroup.org/datasets", "rel": "self"}, 88 | {"href": "http://tall_dset112_deleted.test.hdfgroup.org/groups/289b4873-a2c6-11e4-adfb-3c15c2da029e", "rel": "root"}, 89 | {"href": "http://tall_dset112_deleted.test.hdfgroup.org/", "rel": "home"} 90 | ] 91 | } 92 | 93 | Related Resources 94 | ================= 95 | 96 | * :doc:`GET_Datasets` 97 | * :doc:`GET_Dataset` 98 | * :doc:`POST_Dataset` 99 | 100 | 101 | -------------------------------------------------------------------------------- /Resources.rst: -------------------------------------------------------------------------------- 1 | ************** 2 | Resource List 3 | ************** 4 | 5 | List of Resources 6 | ================= 7 | 8 | +----------------+------+------+------+--------+-----------------------------------------+ 9 | | Resource | GET | PUT | POST | DELETE | Description | 10 | +================+======+======+======+========+=========================================+ 11 | | Domain | Y | Y | N | Y | A related collection of HDF objects | 12 | +----------------+------+------+------+--------+-----------------------------------------+ 13 | | Group | Y | N | N | Y | Represents an HDF Group | 14 | +----------------+------+------+------+--------+-----------------------------------------+ 15 | | Links | Y | N | N | N | Collection of links within a group | 16 | +----------------+------+------+------+--------+-----------------------------------------+ 17 | | Link | Y | Y | N | Y | Represents an HDF link | 18 | +----------------+------+------+------+--------+-----------------------------------------+ 19 | | Dataset | Y | N | N | Y | Represents an HDF Dataset | 20 | +----------------+------+------+------+--------+-----------------------------------------+ 21 | | Attributes | Y | N | N | N | Collection of Attributes | 22 | +----------------+------+------+------+--------+-----------------------------------------+ 23 | | Attribute | Y | Y | N | Y | Represents an HDF Attribute | 24 | +----------------+------+------+------+--------+-----------------------------------------+ 25 | | Dataspace | Y | Y | N | N | Shape of a dataset | 26 | +----------------+------+------+------+--------+-----------------------------------------+ 27 | | Type | Y | N | N | N | Type of a dataset | 28 | +----------------+------+------+------+--------+-----------------------------------------+ 29 | | Value | Y | Y | Y | N | Data values of a datset | 30 | +----------------+------+------+------+--------+-----------------------------------------+ 31 | | Datatype | Y | N | N | Y | Committed datatype | 32 | +----------------+------+------+------+--------+-----------------------------------------+ 33 | | Groups | Y | N | Y | N | Collection of groups within a domain | 34 | +----------------+------+------+------+--------+-----------------------------------------+ 35 | | Datasets | Y | N | Y | N | Collection of datasets within a domain | 36 | +----------------+------+------+------+--------+-----------------------------------------+ 37 | | Datatypes | Y | N | Y | N | Collection of datatypes within a domain | 38 | +----------------+------+------+------+--------+-----------------------------------------+ 39 | 40 | 41 | -------------------------------------------------------------------------------- /DatasetOps/PUT_DatasetShape.md: -------------------------------------------------------------------------------- 1 | PUT Shape 2 | ========= 3 | 4 | Description 5 | ----------- 6 | 7 | Modifies the dimensions of a dataset. Dimensions can only be changed if the dataset was initially created with that dimension as *extensible* - i.e. the maxdims value for that dimension is larger than the initial dimension size (or maxdims set to 0). 8 | 9 | *Note:* Dimensions can only be made larger, they can not be reduced. 10 | 11 | Requests 12 | -------- 13 | 14 | ### Syntax 15 | 16 | ``` sourceCode 17 | PUT /datasets//shape HTTP/1.1 18 | Host: DOMAIN 19 | Authorization: 20 | ``` 21 | 22 | *<id>* is the UUID of the dataset whose shape will be modified. 23 | 24 | ### Request Parameters 25 | 26 | This implementation of the operation does not use request parameters. 27 | 28 | ### Request Headers 29 | 30 | This implementation of the operation uses only the request headers that are common to most requests. See ../CommonRequestHeaders 31 | 32 | ### Request Elements 33 | 34 | The request body must include a JSON object with a "shape" key as described below: 35 | 36 | #### shape 37 | 38 | An integer array giving the new dimensions of the dataset. 39 | 40 | Responses 41 | --------- 42 | 43 | ### Response Headers 44 | 45 | This implementation of the operation uses only response headers that are common to most responses. See ../CommonResponseHeaders. 46 | 47 | ### Response Elements 48 | 49 | On success, a JSON response will be returned with the following elements: 50 | 51 | #### hrefs 52 | 53 | An array of links to related resources. See ../Hypermedia. 54 | 55 | ### Special Errors 56 | 57 | This implementation of the operation does not return special errors. For general information on standard error codes, see ../CommonErrorResponses. 58 | 59 | Examples 60 | -------- 61 | 62 | ### Sample Request 63 | 64 | ``` sourceCode 65 | PUT /datasets/b9b6acc0-a839-11e4-aa86-3c15c2da029e/shape HTTP/1.1 66 | Content-Length: 19 67 | User-Agent: python-requests/2.3.0 CPython/2.7.8 Darwin/14.0.0 68 | host: resized.test.hdfgroup.org 69 | Accept: */* 70 | Accept-Encoding: gzip, deflate 71 | ``` 72 | 73 | ``` sourceCode 74 | { 75 | "shape": [10, 25] 76 | } 77 | ``` 78 | 79 | ### Sample Response 80 | 81 | ``` sourceCode 82 | HTTP/1.1 201 Created 83 | Date: Fri, 30 Jan 2015 04:47:47 GMT 84 | Content-Length: 331 85 | Content-Type: application/json 86 | Server: TornadoServer/3.2.2 87 | ``` 88 | 89 | ``` sourceCode 90 | { 91 | "hrefs": [ 92 | {"href": "http://resized.test.hdfgroup.org/datasets/22e1b235-a83b-11e4-97f4-3c15c2da029e", "rel": "self"}, 93 | {"href": "http://resized.test.hdfgroup.org/datasets/22e1b235-a83b-11e4-97f4-3c15c2da029e", "rel": "owner"}, 94 | {"href": "http://resized.test.hdfgroup.org/groups/22dfff8f-a83b-11e4-883d-3c15c2da029e", "rel": "root"} 95 | ] 96 | } 97 | ``` 98 | 99 | Related Resources 100 | ----------------- 101 | 102 | - GET\_Dataset 103 | - GET\_DatasetShape 104 | - GET\_Value 105 | - POST\_Value 106 | - PUT\_Value 107 | 108 | -------------------------------------------------------------------------------- /DatasetOps/POST_Value.rst: -------------------------------------------------------------------------------- 1 | ********************************************** 2 | POST Value 3 | ********************************************** 4 | 5 | Description 6 | =========== 7 | Gets values of a dataset for a given point selection (provided in the body of the 8 | request). 9 | 10 | Requests 11 | ======== 12 | 13 | Syntax 14 | ------ 15 | .. code-block:: http 16 | 17 | POST /datasets//value HTTP/1.1 18 | Host: DOMAIN 19 | Authorization: 20 | 21 | ** is the UUID of the requested dataset t 22 | 23 | Request Parameters 24 | ------------------ 25 | This implementation of the operation does not use request parameters. 26 | 27 | Request Headers 28 | --------------- 29 | This implementation of the operation uses only the request headers that are common 30 | to most requests. See :doc:`../CommonRequestHeaders` 31 | 32 | Request Body 33 | ------------ 34 | 35 | The request body should be a JSON object with the following key: 36 | 37 | points 38 | ^^^^^^ 39 | 40 | An array of points defining the selection. Each point can either be an integer 41 | (if the dataset has just one dimension), or an array where the length of the 42 | array is equal to the number of dimensions of the dataset. 43 | 44 | Responses 45 | ========= 46 | 47 | Response Headers 48 | ---------------- 49 | 50 | This implementation of the operation uses only response headers that are common to 51 | most responses. See :doc:`../CommonResponseHeaders`. 52 | 53 | Response Elements 54 | ----------------- 55 | 56 | On success, a JSON response will be returned with the following elements: 57 | 58 | value 59 | ^^^^^ 60 | An array of values where the length of the array is equal to the number of points 61 | in the request. Each value will be a string, integer, or JSON object consistent 62 | with the dataset type (e.g. a compound type). 63 | 64 | Special Errors 65 | -------------- 66 | 67 | This implementation of the operation does not return special errors. For general 68 | information on standard error codes, see :doc:`../CommonErrorResponses`. 69 | 70 | Examples 71 | ======== 72 | 73 | Sample Request 74 | -------------- 75 | 76 | .. code-block:: http 77 | 78 | POST /datasets/4e83ad1c-ab6e-11e4-babb-3c15c2da029e/value HTTP/1.1 79 | Content-Length: 92 80 | User-Agent: python-requests/2.3.0 CPython/2.7.8 Darwin/14.0.0 81 | host: tall.test.hdfgroup.org 82 | Accept: */* 83 | Accept-Encoding: gzip, deflate 84 | 85 | .. code-block:: json 86 | 87 | { 88 | "points": [19, 17, 13, 11, 7, 5, 3, 2] 89 | } 90 | 91 | Sample Response 92 | --------------- 93 | 94 | .. code-block:: http 95 | 96 | HTTP/1.1 200 OK 97 | Date: Tue, 03 Feb 2015 06:31:38 GMT 98 | Content-Length: 47 99 | Content-Type: application/json 100 | Server: TornadoServer/3.2.2 101 | 102 | .. code-block:: json 103 | 104 | { 105 | "value": [0, 1, 4, 9, 16, 25, 36, 49, 64, 81] 106 | } 107 | 108 | Related Resources 109 | ================= 110 | 111 | * :doc:`GET_Dataset` 112 | * :doc:`GET_Value` 113 | * :doc:`PUT_Value` 114 | 115 | 116 | -------------------------------------------------------------------------------- /GroupOps/DELETE_Link.rst: -------------------------------------------------------------------------------- 1 | ********************************************** 2 | DELETE Link 3 | ********************************************** 4 | 5 | Description 6 | =========== 7 | The implementation of the DELETE operation deletes the link named in the URI. 8 | 9 | Groups, datatypes, and datasets that are referenced by the link will **not** be 10 | deleted. To delete groups, datatypes or datasets, use the appropriate DELETE operation 11 | for those objects. 12 | 13 | Requests 14 | ======== 15 | 16 | Syntax 17 | ------ 18 | .. code-block:: http 19 | 20 | DELETE /groups//links/ HTTP/1.1 21 | X-Hdf-domain: DOMAIN 22 | Authorization: 23 | 24 | .. code-block:: http 25 | 26 | DELETE /groups//links/?domain=DOMAIN HTTP/1.1 27 | Authorization: 28 | 29 | * ** is the UUID of the group the link is a member of. 30 | * ** is the URL-encoded name of the link. 31 | 32 | 33 | Request Parameters 34 | ------------------ 35 | This implementation of the operation does not use request parameters. 36 | 37 | Request Headers 38 | --------------- 39 | This implementation of the operation uses only the request headers that are common 40 | to most requests. See :doc:`../CommonRequestHeaders` 41 | 42 | Responses 43 | ========= 44 | 45 | Response Headers 46 | ---------------- 47 | 48 | This implementation of the operation uses only response headers that are common to 49 | most responses. See :doc:`../CommonResponseHeaders`. 50 | 51 | Response Elements 52 | ----------------- 53 | 54 | On success, a JSON response will be returned with the following elements: 55 | 56 | hrefs 57 | ^^^^^ 58 | An array of links to related resources. See :doc:`../Hypermedia`. 59 | 60 | Special Errors 61 | -------------- 62 | 63 | An attempt to delete the root group will return 403 - Forbidden. For general 64 | information on standard error codes, see :doc:`../CommonErrorResponses`. 65 | 66 | Examples 67 | ======== 68 | 69 | Sample Request 70 | -------------- 71 | 72 | .. code-block:: http 73 | 74 | DELETE /groups/g-b116b6f0-85e9-11e8-9cc2-0242ac120008/links/deleteme HTTP/1.1 75 | Host: hsdshdflab.hdfgroup.org 76 | X-Hdf-domain: /shared/tall.h5 77 | Content-Length: 0 78 | Accept: */* 79 | Accept-Encoding: gzip, deflate 80 | 81 | Sample cURL command 82 | ------------------- 83 | 84 | .. code-block:: bash 85 | 86 | $ curl -X DELETE -u username:password --header "X-Hdf-domain: /shared/tall.h5" hsdshdflab.hdfgroup.org/groups/g-b116b6f0-85e9-11e8-9cc2-0242ac120008/links/deleteme 87 | 88 | Sample Response 89 | --------------- 90 | 91 | .. code-block:: http 92 | 93 | HTTP/1.1 200 OK 94 | Date: Thu, 12 Jul 2018 19:45:54 GMT 95 | Content-Length: 12 96 | Content-Type: application/json 97 | Server: nginx/1.15.0 98 | 99 | .. code-block:: json 100 | 101 | {"href": []} 102 | 103 | Related Resources 104 | ================= 105 | 106 | * :doc:`../DatasetOps/DELETE_Dataset` 107 | * :doc:`../DatatypeOps/DELETE_Datatype` 108 | * :doc:`DELETE_Group` 109 | * :doc:`GET_Link` 110 | * :doc:`GET_Groups` 111 | * :doc:`POST_Group` 112 | 113 | 114 | -------------------------------------------------------------------------------- /AttrOps/DELETE_Attribute.md: -------------------------------------------------------------------------------- 1 | DELETE Attribute 2 | ================ 3 | 4 | Description 5 | ----------- 6 | 7 | The implementation of the DELETE operation deletes the attribute named in the URI. 8 | 9 | Requests 10 | -------- 11 | 12 | ### Syntax 13 | 14 | ``` sourceCode 15 | DELETE /groups// HTTP/1.1 16 | X-Hdf-domain: DOMAIN 17 | Authorization: 18 | ``` 19 | 20 | ``` sourceCode 21 | DELETE /groups//?domain=DOMAIN HTTP/1.1 22 | Authorization: 23 | ``` 24 | 25 | ``` sourceCode 26 | DELETE /datasets// HTTP/1.1 27 | X-Hdf-domain: DOMAIN 28 | Authorization: 29 | ``` 30 | 31 | ``` sourceCode 32 | DELETE /datasets//?domain=DOMAIN HTTP/1.1 33 | Authorization: 34 | ``` 35 | 36 | ``` sourceCode 37 | DELETE /datatypess// HTTP/1.1 38 | X-Hdf-domain: DOMAIN 39 | Authorization: 40 | ``` 41 | 42 | ``` sourceCode 43 | DELETE /datatypes//?domain=DOMAIN HTTP/1.1 44 | Authorization: 45 | ``` 46 | 47 | - *<id>* is the UUID of the dataset/group/committed datatype 48 | - *<name>* is the url-encoded name of the requested attribute 49 | 50 | ### Request Parameters 51 | 52 | This implementation of the operation does not use request parameters. 53 | 54 | ### Request Headers 55 | 56 | This implementation of the operation uses only the request headers that are common to most requests. See ../CommonRequestHeaders 57 | 58 | Responses 59 | --------- 60 | 61 | ### Response Headers 62 | 63 | This implementation of the operation uses only response headers that are common to most responses. See ../CommonResponseHeaders. 64 | 65 | ### Response Elements 66 | 67 | On success, a JSON response will be returned with the following elements: 68 | 69 | #### hrefs 70 | 71 | An array of links to related resources. See ../Hypermedia. 72 | 73 | ### Special Errors 74 | 75 | This implementation of the operation does not return special errors. For general information on standard error codes, see ../CommonErrorResponses. 76 | 77 | Examples 78 | -------- 79 | 80 | ### Sample Request 81 | 82 | ``` sourceCode 83 | DELETE /groups/g-45f464d8-883e-11e8-a9dc-0242ac12000e/attributes/attr1 HTTP/1.1 84 | Host: hsdshdflab.hdfgroup.org 85 | X-Hdf-domain: /shared/tall.h5 86 | Accept: */* 87 | Accept-Encoding: gzip, deflate 88 | ``` 89 | 90 | ### Sample cURL command 91 | 92 | ``` sourceCode 93 | $ curl -X DELETE -u username:password --header "X-Hdf-domain: /shared/tall.h5" hsdshdflab.hdfgroup.org/groups/g-45f464d8-883e-11e8-a9dc-0242ac12000e/attributes/attr1 94 | ``` 95 | 96 | ### Sample Response 97 | 98 | ``` sourceCode 99 | HTTP/1.1 200 OK 100 | Date: Sun, 15 Jul 2018 16:06:54 GMT 101 | Content-Length: 13 102 | Content-Type: application/json 103 | Server: nginx/1.15.0 104 | ``` 105 | 106 | ``` sourceCode 107 | {"hrefs": []} 108 | ``` 109 | 110 | Related Resources 111 | ----------------- 112 | 113 | - GET\_Attributes 114 | - GET\_Attribute 115 | - ../DatasetOps/GET\_Dataset 116 | - ../DatatypeOps/GET\_Datatype 117 | - ../GroupOps/GET\_Group 118 | - PUT\_Attribute 119 | 120 | -------------------------------------------------------------------------------- /DatasetOps/index.md: -------------------------------------------------------------------------------- 1 | Datasets 2 | ======== 3 | 4 | Datasets are objects that are composed of a homogenous collection of data elements. Each dataset has a *type* that specifies the structure of the individual elements (float, string, compound, etc.), and a *shape* that specifies the layout of the data elements (scalar, one-dimensional, multi-dimensional). In addition, meta-data can be attached to a dataset in the form of attributes. See: ../AttrOps/index. 5 | 6 | Creating Datasets 7 | ----------------- 8 | 9 | Use the POST\_Dataset operation to create new datasets. As part of the POST request, JSON descriptions for the type and shape of the dataset are included with the request. Optionally, creation properties can be used to specify the chunk layout (how the data elements are stored in the server) and compression filters (e.g. GZIP, LZF, SZIP). 10 | 11 | Getting information about a dataset 12 | ----------------------------------- 13 | 14 | Use the GET\_Dataset operation to retrieve information about a dataset's type, shape, creation properties, and number of attributes. To list all the datasets within a domain use GET\_Datasets. To list the datasets linked to a particular group use ../GroupOps/GET\_Links and look at links with a "collection" key of "datasets". 15 | 16 | Writing data to a dataset 17 | ------------------------- 18 | 19 | To write data into the dataset, use the PUT\_Value operation. The request can either provide values for the entire dataset, or values for a hyperslab (rectangular sub-region) selection. In addition, if it desired to update a specific list of data elements, a point selection (series of element coordinates) can be passed to the PUT\_Value operation. 20 | 21 | Reading data from a dataset 22 | --------------------------- 23 | 24 | To read either the entire dataset, or a specified selection, use the GET\_Value operation. Without any request parameters, the GET operation returns all data values. To read a specific hyperslab, use the select parameter to specify the start and end indices of the hyperslab (the selection can also include a step value to include a regular subset of the hyperslab). Finally, for one-dimensional datasets with compound types, a *where* parameter can be used to select elements meeting a specified condition. 25 | 26 | To read a specific list of elements (by index values), use the POST\_Value operation (POST is used in this case rather than GET since the point selection values may be too large to include in the URI.) 27 | 28 | Resizable datasets 29 | ------------------ 30 | 31 | If one or more of the dimensions of a dataset may need to be extended after creation, provide a *maxdims* key to the shape during creation (see POST\_Dataset). If the value of the maxdims dimension is 0, that dimension is *unlimited* and may be extended as much as desired. If an upper limit is known, use that value in maxdims to allow that dimension to be extended up to the given value. To resize the dataset, use the PUT\_DatasetShape operation with the desired shape value(s) for the new dimensions. 32 | 33 | Note: dimensions can only be increased, not decreased. 34 | 35 | Deleting datasets 36 | ----------------- 37 | 38 | The DELETE\_Dataset operation will remove the dataset, its attributes, and any links to the object. 39 | 40 | List of Operations 41 | ------------------ 42 | -------------------------------------------------------------------------------- /.validaterc: -------------------------------------------------------------------------------- 1 | { 2 | "shared": { 3 | "operations": { 4 | "no_operation_id": "warning", 5 | "operation_id_case_convention": [ 6 | "warning", 7 | "lower_snake_case" 8 | ], 9 | "no_summary": "warning", 10 | "no_array_responses": "error", 11 | "parameter_order": "warning", 12 | "undefined_tag": "warning", 13 | "unused_tag": "warning", 14 | "operation_id_naming_convention": "warning" 15 | }, 16 | "pagination": { 17 | "pagination_style": "warning" 18 | }, 19 | "parameters": { 20 | "no_parameter_description": "error", 21 | "param_name_case_convention": [ 22 | "error", 23 | "lower_camel_case" 24 | ], 25 | "invalid_type_format_pair": "error", 26 | "content_type_parameter": "error", 27 | "accept_type_parameter": "error", 28 | "authorization_parameter": "warning", 29 | "required_param_has_default": "warning" 30 | }, 31 | "paths": { 32 | "missing_path_parameter": "error", 33 | "duplicate_path_parameter": "warning", 34 | "snake_case_only": "off", 35 | "paths_case_convention": [ 36 | "error", 37 | "lower_snake_case" 38 | ] 39 | }, 40 | "responses": { 41 | "inline_response_schema": "warning" 42 | }, 43 | "security_definitions": { 44 | "unused_security_schemes": "warning", 45 | "unused_security_scopes": "warning" 46 | }, 47 | "security": { 48 | "invalid_non_empty_security_array": "error" 49 | }, 50 | "schemas": { 51 | "invalid_type_format_pair": "error", 52 | "snake_case_only": "off", 53 | "no_schema_description": "warning", 54 | "no_property_description": "warning", 55 | "description_mentions_json": "warning", 56 | "array_of_arrays": "warning", 57 | "inconsistent_property_type": [ 58 | "warning", 59 | [ 60 | "code", 61 | "default", 62 | "type", 63 | "value" 64 | ] 65 | ], 66 | "property_case_convention": [ 67 | "error", 68 | "lower_camel_case" 69 | ], 70 | "property_case_collision": "error", 71 | "enum_case_convention": [ 72 | "warning", 73 | "lower_snake_case" 74 | ], 75 | "undefined_required_properties": "warning" 76 | }, 77 | "walker": { 78 | "no_empty_descriptions": "error", 79 | "has_circular_references": "warning", 80 | "$ref_siblings": "off", 81 | "duplicate_sibling_description": "warning", 82 | "incorrect_ref_pattern": "warning" 83 | } 84 | }, 85 | "swagger2": { 86 | "operations": { 87 | "no_consumes_for_put_or_post": "error", 88 | "get_op_has_consumes": "warning", 89 | "no_produces": "warning" 90 | } 91 | }, 92 | "oas3": { 93 | "operations": { 94 | "no_request_body_name": "warning" 95 | }, 96 | "responses": { 97 | "no_success_response_codes": "warning", 98 | "protocol_switching_and_success_code": "error", 99 | "no_response_body": "warning", 100 | "ibm_status_code_guidelines": "warning" 101 | }, 102 | "schemas": { 103 | "json_or_param_binary_string": "warning" 104 | } 105 | }, 106 | "spectral": { 107 | "rules": {} 108 | } 109 | } -------------------------------------------------------------------------------- /DomainOps/PUT_Domain.md: -------------------------------------------------------------------------------- 1 | PUT Domain 2 | ========== 3 | 4 | Description 5 | ----------- 6 | 7 | This operation creates a new domain. 8 | 9 | *Note*: Initially the only object contained in the domain is the root group. Use other PUT and POST operations to create new objects in the domain. 10 | 11 | *Note*: The operation will fail if the domain already exists (a 409 code will be returned). 12 | 13 | Requests 14 | -------- 15 | 16 | ### Syntax 17 | 18 | ``` sourceCode 19 | PUT / HTTP/1.1 20 | X-Hdf-domain: DOMAIN 21 | Authorization: 22 | ``` 23 | 24 | ``` sourceCode 25 | PUT /?domain=DOMAIN HTTP/1.1 26 | Authorization: 27 | ``` 28 | 29 | ### Request Parameters 30 | 31 | This implementation of the operation does not use request parameters. 32 | 33 | ### Request Headers 34 | 35 | This implementation of the operation uses only the request headers that are common to most requests. See ../CommonRequestHeaders 36 | 37 | Responses 38 | --------- 39 | 40 | ### Response Headers 41 | 42 | This implementation of the operation uses only response headers that are common to most responses. See ../CommonResponseHeaders. 43 | 44 | ### Response Elements 45 | 46 | On success, a JSON response will be returned with the following elements: 47 | 48 | #### root 49 | 50 | The UUID of the root group of this domain. 51 | 52 | #### created 53 | 54 | A timestamp giving the time the domain was created in UTC (ISO-8601 format). 55 | 56 | #### owner 57 | 58 | The user which owns the domain. 59 | 60 | #### lastModified 61 | 62 | A timestamp giving the most recent time that any content in the domain has been modified in UTC (ISO-8601 format). 63 | 64 | #### acls 65 | 66 | A JSON object representing the ../AclOps/index values for the domain. 67 | 68 | ### Special Errors 69 | 70 | This implementation of the operation does not return any special errors. For general information on standard error codes, see ../CommonErrorResponses. 71 | 72 | An http status code of 409 (Conflict) will be returned if the domain already exists. 73 | 74 | Examples 75 | -------- 76 | 77 | ### Sample Request 78 | 79 | ``` sourceCode 80 | PUT / HTTP/1.1 81 | Host: hsdshdflab.hdfgroup.org 82 | X-Hdf-domain: /shared/newfile.h5 83 | Content-Length: 0 84 | Accept: */* 85 | Accept-Encoding: gzip, deflate 86 | ``` 87 | 88 | ### Sample cURL command 89 | 90 | ``` sourceCode 91 | $ curl -X PUT -u username:password --header "X-Hdf-domain: /shared/newfile.h5" hsdshdflab.hdfgroup.org/ 92 | ``` 93 | 94 | ### Sample Response 95 | 96 | ``` sourceCode 97 | HTTP/1.1 201 Created 98 | Date: Thu, 12 Jul 2018 16:16:34 GMT 99 | Content-Length: 380 100 | Content-Type: application/json 101 | Server: nginx/1.15.0 102 | ``` 103 | 104 | ``` sourceCode 105 | { 106 | "root": "g-a6915d1a-85ef-11e8-8659-0242ac12000c", 107 | "created": 1531412497.967022, 108 | "owner": "test_user1", 109 | "lastModified": 1531412497.967022, 110 | "acls": { 111 | "default": {"updateACL": false, "read": true, "delete": false, "update": false, "create": false, "readACL": false}, 112 | "test_user1": {"updateACL": true, "read": true, "delete": true, "update": true, "create": true, "readACL": true} 113 | } 114 | } 115 | ``` 116 | 117 | Related Resources 118 | ----------------- 119 | 120 | - DELETE\_Domain 121 | - ../GroupOps/GET\_Group 122 | - GET\_Domain 123 | 124 | -------------------------------------------------------------------------------- /DatasetOps/PUT_DatasetShape.rst: -------------------------------------------------------------------------------- 1 | ********************************************** 2 | PUT Shape 3 | ********************************************** 4 | 5 | Description 6 | =========== 7 | Modifies the dimensions of a dataset. Dimensions can only be changed if the dataset 8 | was initially created with that dimension as *extensible* - i.e. the maxdims value 9 | for that dimension is larger than the initial dimension size (or maxdims set to 0). 10 | 11 | *Note:* Dimensions can only be made larger, they can not be reduced. 12 | 13 | Requests 14 | ======== 15 | 16 | Syntax 17 | ------ 18 | .. code-block:: http 19 | 20 | PUT /datasets//shape HTTP/1.1 21 | Host: DOMAIN 22 | Authorization: 23 | 24 | ** is the UUID of the dataset whose shape will be modified. 25 | 26 | Request Parameters 27 | ------------------ 28 | This implementation of the operation does not use request parameters. 29 | 30 | Request Headers 31 | --------------- 32 | This implementation of the operation uses only the request headers that are common 33 | to most requests. See :doc:`../CommonRequestHeaders` 34 | 35 | Request Elements 36 | ---------------- 37 | The request body must include a JSON object with a "shape" key as described below: 38 | 39 | shape 40 | ^^^^^ 41 | An integer array giving the new dimensions of the dataset. 42 | 43 | Responses 44 | ========= 45 | 46 | Response Headers 47 | ---------------- 48 | 49 | This implementation of the operation uses only response headers that are common to 50 | most responses. See :doc:`../CommonResponseHeaders`. 51 | 52 | Response Elements 53 | ----------------- 54 | 55 | On success, a JSON response will be returned with the following elements: 56 | 57 | hrefs 58 | ^^^^^ 59 | An array of links to related resources. See :doc:`../Hypermedia`. 60 | 61 | Special Errors 62 | -------------- 63 | 64 | This implementation of the operation does not return special errors. For general 65 | information on standard error codes, see :doc:`../CommonErrorResponses`. 66 | 67 | Examples 68 | ======== 69 | 70 | Sample Request 71 | -------------- 72 | 73 | .. code-block:: http 74 | 75 | PUT /datasets/b9b6acc0-a839-11e4-aa86-3c15c2da029e/shape HTTP/1.1 76 | Content-Length: 19 77 | User-Agent: python-requests/2.3.0 CPython/2.7.8 Darwin/14.0.0 78 | host: resized.test.hdfgroup.org 79 | Accept: */* 80 | Accept-Encoding: gzip, deflate 81 | 82 | .. code-block:: json 83 | 84 | { 85 | "shape": [10, 25] 86 | } 87 | 88 | Sample Response 89 | --------------- 90 | 91 | .. code-block:: http 92 | 93 | HTTP/1.1 201 Created 94 | Date: Fri, 30 Jan 2015 04:47:47 GMT 95 | Content-Length: 331 96 | Content-Type: application/json 97 | Server: TornadoServer/3.2.2 98 | 99 | .. code-block:: json 100 | 101 | { 102 | "hrefs": [ 103 | {"href": "http://resized.test.hdfgroup.org/datasets/22e1b235-a83b-11e4-97f4-3c15c2da029e", "rel": "self"}, 104 | {"href": "http://resized.test.hdfgroup.org/datasets/22e1b235-a83b-11e4-97f4-3c15c2da029e", "rel": "owner"}, 105 | {"href": "http://resized.test.hdfgroup.org/groups/22dfff8f-a83b-11e4-883d-3c15c2da029e", "rel": "root"} 106 | ] 107 | } 108 | 109 | Related Resources 110 | ================= 111 | 112 | * :doc:`GET_Dataset` 113 | * :doc:`GET_DatasetShape` 114 | * :doc:`GET_Value` 115 | * :doc:`POST_Value` 116 | * :doc:`PUT_Value` 117 | 118 | 119 | -------------------------------------------------------------------------------- /AttrOps/DELETE_Attribute.rst: -------------------------------------------------------------------------------- 1 | ********************************************** 2 | DELETE Attribute 3 | ********************************************** 4 | 5 | Description 6 | =========== 7 | The implementation of the DELETE operation deletes the attribute named in the URI. 8 | 9 | Requests 10 | ======== 11 | 12 | Syntax 13 | ------ 14 | .. code-block:: http 15 | 16 | DELETE /groups// HTTP/1.1 17 | X-Hdf-domain: DOMAIN 18 | Authorization: 19 | 20 | .. code-block:: http 21 | 22 | DELETE /groups//?domain=DOMAIN HTTP/1.1 23 | Authorization: 24 | 25 | .. code-block:: http 26 | 27 | DELETE /datasets// HTTP/1.1 28 | X-Hdf-domain: DOMAIN 29 | Authorization: 30 | 31 | .. code-block:: http 32 | 33 | DELETE /datasets//?domain=DOMAIN HTTP/1.1 34 | Authorization: 35 | 36 | .. code-block:: http 37 | 38 | DELETE /datatypess// HTTP/1.1 39 | X-Hdf-domain: DOMAIN 40 | Authorization: 41 | 42 | .. code-block:: http 43 | 44 | DELETE /datatypes//?domain=DOMAIN HTTP/1.1 45 | Authorization: 46 | 47 | * ** is the UUID of the dataset/group/committed datatype 48 | * ** is the url-encoded name of the requested attribute 49 | 50 | Request Parameters 51 | ------------------ 52 | This implementation of the operation does not use request parameters. 53 | 54 | Request Headers 55 | --------------- 56 | This implementation of the operation uses only the request headers that are common 57 | to most requests. See :doc:`../CommonRequestHeaders` 58 | 59 | Responses 60 | ========= 61 | 62 | Response Headers 63 | ---------------- 64 | 65 | This implementation of the operation uses only response headers that are common to 66 | most responses. See :doc:`../CommonResponseHeaders`. 67 | 68 | Response Elements 69 | ----------------- 70 | 71 | On success, a JSON response will be returned with the following elements: 72 | 73 | hrefs 74 | ^^^^^ 75 | An array of links to related resources. See :doc:`../Hypermedia`. 76 | 77 | Special Errors 78 | -------------- 79 | 80 | This implementation of the operation does not return special errors. For general 81 | information on standard error codes, see :doc:`../CommonErrorResponses`. 82 | 83 | Examples 84 | ======== 85 | 86 | Sample Request 87 | -------------- 88 | 89 | .. code-block:: http 90 | 91 | DELETE /groups/g-45f464d8-883e-11e8-a9dc-0242ac12000e/attributes/attr1 HTTP/1.1 92 | Host: hsdshdflab.hdfgroup.org 93 | X-Hdf-domain: /shared/tall.h5 94 | Accept: */* 95 | Accept-Encoding: gzip, deflate 96 | 97 | Sample cURL command 98 | ------------------- 99 | 100 | .. code-block:: bash 101 | 102 | $ curl -X DELETE -u username:password --header "X-Hdf-domain: /shared/tall.h5" hsdshdflab.hdfgroup.org/groups/g-45f464d8-883e-11e8-a9dc-0242ac12000e/attributes/attr1 103 | 104 | Sample Response 105 | --------------- 106 | 107 | .. code-block:: http 108 | 109 | HTTP/1.1 200 OK 110 | Date: Sun, 15 Jul 2018 16:06:54 GMT 111 | Content-Length: 13 112 | Content-Type: application/json 113 | Server: nginx/1.15.0 114 | 115 | .. code-block:: json 116 | 117 | {"hrefs": []} 118 | 119 | Related Resources 120 | ================= 121 | 122 | * :doc:`GET_Attributes` 123 | * :doc:`GET_Attribute` 124 | * :doc:`../DatasetOps/GET_Dataset` 125 | * :doc:`../DatatypeOps/GET_Datatype` 126 | * :doc:`../GroupOps/GET_Group` 127 | * :doc:`PUT_Attribute` 128 | 129 | 130 | -------------------------------------------------------------------------------- /DatasetOps/index.rst: -------------------------------------------------------------------------------- 1 | ###################### 2 | Datasets 3 | ###################### 4 | 5 | Datasets are objects that are composed of a homogenous collection of data elements. Each 6 | dataset has a *type* that specifies the structure of the individual elements (float, string, 7 | compound, etc.), and a *shape* that specifies the layout of the data elements (scalar, 8 | one-dimensional, multi-dimensional). In addition, meta-data can be attached to a dataset 9 | in the form of attributes. See: :doc:`../AttrOps/index`. 10 | 11 | Creating Datasets 12 | ----------------- 13 | 14 | Use the :doc:`POST_Dataset` operation to create new datasets. As part of the POST 15 | request, JSON descriptions for the type and shape of the dataset are included with the 16 | request. Optionally, creation properties can be used to specify the chunk layout (how 17 | the data elements are stored in the server) and compression filters (e.g. GZIP, LZF, SZIP). 18 | 19 | Getting information about a dataset 20 | ----------------------------------- 21 | Use the :doc:`GET_Dataset` operation to retrieve information about a dataset's type, 22 | shape, creation properties, and number of attributes. To list all the datasets within a domain use 23 | :doc:`GET_Datasets`. To list the datasets linked to a particular group use 24 | :doc:`../GroupOps/GET_Links` and look at links with a "collection" key of "datasets". 25 | 26 | Writing data to a dataset 27 | ------------------------- 28 | To write data into the dataset, use the :doc:`PUT_Value` operation. The request can 29 | either provide values for the entire dataset, or values for a hyperslab (rectangular 30 | sub-region) selection. In addition, if it desired to update a specific list of 31 | data elements, a point selection (series of element coordinates) can be passed to the 32 | :doc:`PUT_Value` operation. 33 | 34 | Reading data from a dataset 35 | --------------------------- 36 | To read either the entire dataset, or a specified selection, use the :doc:`GET_Value` 37 | operation. Without any request parameters, the GET operation returns all data values. 38 | To read a specific hyperslab, use the select parameter to specify the start and end indices 39 | of the hyperslab (the selection can also include a step value to include a regular subset of the hyperslab). 40 | Finally, for one-dimensional datasets with compound types, a *where* parameter can be used to 41 | select elements meeting a specified condition. 42 | 43 | To read a specific list of elements (by index values), use the :doc:`POST_Value` operation (POST is 44 | used in this case rather than GET since the point selection values may be too 45 | large to include in the URI.) 46 | 47 | Resizable datasets 48 | ------------------ 49 | If one or more of the dimensions of a dataset may need to be extended after creation, 50 | provide a *maxdims* key to the shape during creation (see :doc:`POST_Dataset`). If the value of the maxdims 51 | dimension is 0, that dimension is *unlimited* and may be extended as much as desired. 52 | If an upper limit is known, use that value in maxdims to allow that dimension 53 | to be extended up to the given value. 54 | To resize the dataset, use the :doc:`PUT_DatasetShape` operation with the desired shape value(s) for 55 | the new dimensions. 56 | 57 | Note: dimensions can only be increased, not decreased. 58 | 59 | Deleting datasets 60 | ----------------- 61 | The :doc:`DELETE_Dataset` operation will remove the dataset, its attributes, and any 62 | links to the object. 63 | 64 | List of Operations 65 | ------------------- 66 | 67 | .. toctree:: 68 | :maxdepth: 1 69 | 70 | DELETE_Dataset 71 | GET_Dataset 72 | GET_Datasets 73 | GET_DatasetShape 74 | GET_DatasetType 75 | GET_Value 76 | POST_Dataset 77 | POST_Value 78 | PUT_DatasetShape 79 | PUT_Value 80 | 81 | 82 | -------------------------------------------------------------------------------- /DomainOps/PUT_Domain.rst: -------------------------------------------------------------------------------- 1 | ********************************************** 2 | PUT Domain 3 | ********************************************** 4 | 5 | Description 6 | =========== 7 | This operation creates a new domain. 8 | 9 | *Note*: Initially the only object contained in the domain is the root group. Use other 10 | PUT and POST operations to create new objects in the domain. 11 | 12 | *Note*: The operation will fail if the domain already exists (a 409 code will be returned). 13 | 14 | Requests 15 | ======== 16 | 17 | Syntax 18 | ------ 19 | .. code-block:: http 20 | 21 | PUT / HTTP/1.1 22 | X-Hdf-domain: DOMAIN 23 | Authorization: 24 | 25 | .. code-block:: http 26 | 27 | PUT /?domain=DOMAIN HTTP/1.1 28 | Authorization: 29 | 30 | Request Parameters 31 | ------------------ 32 | This implementation of the operation does not use request parameters. 33 | 34 | Request Headers 35 | --------------- 36 | This implementation of the operation uses only the request headers that are common 37 | to most requests. See :doc:`../CommonRequestHeaders` 38 | 39 | Responses 40 | ========= 41 | 42 | Response Headers 43 | ---------------- 44 | 45 | This implementation of the operation uses only response headers that are common to 46 | most responses. See :doc:`../CommonResponseHeaders`. 47 | 48 | Response Elements 49 | ----------------- 50 | 51 | On success, a JSON response will be returned with the following elements: 52 | 53 | root 54 | ^^^^ 55 | The UUID of the root group of this domain. 56 | 57 | created 58 | ^^^^^^^ 59 | A timestamp giving the time the domain was created in UTC (ISO-8601 format). 60 | 61 | owner 62 | ^^^^^ 63 | The user which owns the domain. 64 | 65 | lastModified 66 | ^^^^^^^^^^^^ 67 | A timestamp giving the most recent time that any content in the domain has been 68 | modified in UTC (ISO-8601 format). 69 | 70 | acls 71 | ^^^^ 72 | A JSON object representing the :doc:`../AclOps/index` values for the domain. 73 | 74 | Special Errors 75 | -------------- 76 | 77 | This implementation of the operation does not return any special errors. For general 78 | information on standard error codes, see :doc:`../CommonErrorResponses`. 79 | 80 | An http status code of 409 (Conflict) will be returned if the domain already exists. 81 | 82 | Examples 83 | ======== 84 | 85 | Sample Request 86 | -------------- 87 | 88 | .. code-block:: http 89 | 90 | PUT / HTTP/1.1 91 | Host: hsdshdflab.hdfgroup.org 92 | X-Hdf-domain: /shared/newfile.h5 93 | Content-Length: 0 94 | Accept: */* 95 | Accept-Encoding: gzip, deflate 96 | 97 | Sample cURL command 98 | ------------------- 99 | 100 | .. code-block:: bash 101 | 102 | $ curl -X PUT -u username:password --header "X-Hdf-domain: /shared/newfile.h5" hsdshdflab.hdfgroup.org/ 103 | 104 | Sample Response 105 | --------------- 106 | 107 | .. code-block:: http 108 | 109 | HTTP/1.1 201 Created 110 | Date: Thu, 12 Jul 2018 16:16:34 GMT 111 | Content-Length: 380 112 | Content-Type: application/json 113 | Server: nginx/1.15.0 114 | 115 | .. code-block:: json 116 | 117 | { 118 | "root": "g-a6915d1a-85ef-11e8-8659-0242ac12000c", 119 | "created": 1531412497.967022, 120 | "owner": "test_user1", 121 | "lastModified": 1531412497.967022, 122 | "acls": { 123 | "default": {"updateACL": false, "read": true, "delete": false, "update": false, "create": false, "readACL": false}, 124 | "test_user1": {"updateACL": true, "read": true, "delete": true, "update": true, "create": true, "readACL": true} 125 | } 126 | } 127 | 128 | Related Resources 129 | ================= 130 | 131 | * :doc:`DELETE_Domain` 132 | * :doc:`../GroupOps/GET_Group` 133 | * :doc:`GET_Domain` 134 | 135 | 136 | -------------------------------------------------------------------------------- /GroupOps/GET_Group.md: -------------------------------------------------------------------------------- 1 | GET Group 2 | ========= 3 | 4 | Description 5 | ----------- 6 | 7 | Returns information about the group with the UUID given in the URI. 8 | 9 | Requests 10 | -------- 11 | 12 | ### Syntax 13 | 14 | ``` sourceCode 15 | GET /groups/ HTTP/1.1 16 | X-Hdf-domain: DOMAIN 17 | Authorization: 18 | ``` 19 | 20 | ``` sourceCode 21 | GET /groups/?domain=DOMAIN HTTP/1.1 22 | Authorization: 23 | ``` 24 | 25 | *<id>* is the UUID of the requested group. 26 | 27 | ### Request Parameters 28 | 29 | #### include\_links 30 | 31 | If this request parameter is provided, the links of the group are included in the response. 32 | 33 | ### Request Headers 34 | 35 | This implementation of the operation uses only the request headers that are common to most requests. See ../CommonRequestHeaders 36 | 37 | Responses 38 | --------- 39 | 40 | ### Response Headers 41 | 42 | This implementation of the operation uses only response headers that are common to most responses. See ../CommonResponseHeaders. 43 | 44 | ### Response Elements 45 | 46 | On success, a JSON response will be returned with the following elements: 47 | 48 | #### id 49 | 50 | The UUID of the requested group. 51 | 52 | #### root 53 | 54 | The root group of the domain that the group is within. 55 | 56 | #### attributeCount 57 | 58 | The number of attributes belonging to the group. 59 | 60 | #### linkCount 61 | 62 | The number of links belonging to the group. 63 | 64 | #### created 65 | 66 | A timestamp giving the time the group was created in UTC (ISO-8601 format). 67 | 68 | #### lastModified 69 | 70 | A timestamp giving the most recent time the group has been modified (i.e. attributes or links updated) in UTC (ISO-8601 format). 71 | 72 | #### hrefs 73 | 74 | An array of hypertext links to related resources. See ../Hypermedia. 75 | 76 | ### Special Errors 77 | 78 | This implementation of the operation does not return special errors. For general information on standard error codes, see ../CommonErrorResponses. 79 | 80 | Examples 81 | -------- 82 | 83 | ### Sample Request 84 | 85 | ``` sourceCode 86 | GET /groups/g-be6eb652-83c5-11e8-b9ee-0242ac12000a HTTP/1.1 87 | Host: hsdshdflab.hdfgroup.org 88 | X-Hdf-domain: /shared/tall.h5 89 | Accept-Encoding: gzip, deflate 90 | Accept: */* 91 | ``` 92 | 93 | ### Sample cURL command 94 | 95 | ``` sourceCode 96 | $ curl -X GET --header "X-Hdf-domain: /shared/tall.h5" hsdshdflab.hdfgroup.org/groups/g-be6eb652-83c5-11e8-b9ee-0242ac12000a 97 | ``` 98 | 99 | ### Sample Response 100 | 101 | ``` sourceCode 102 | HTTP/1.1 200 OK 103 | Date: Thu, 12 Jul 2018 18:27:24 GMT 104 | Content-Length: 711 105 | Etag: "2c410d1c469786f25ed0075571a8e7a3f313cec1" 106 | Content-Type: application/json 107 | Server: nginx/1.15.0 108 | ``` 109 | 110 | ``` sourceCode 111 | { 112 | "id": "g-be6eb652-83c5-11e8-b9ee-0242ac12000a", 113 | "root": "g-be5996fa-83c5-11e8-a8e6-0242ac120016", 114 | "linkCount": 2, 115 | "attributeCount": 0, 116 | "lastModified": 1531174596.5785563, 117 | "created": 1531174596.2463753, 118 | "domain": "/shared/tall.h5", 119 | "hrefs": [ 120 | {"href": "hsdshdflab.hdfgroup.org/groups/g-be6eb652-83c5-11e8-b9ee-0242ac12000a", "rel": "self"}, 121 | {"href": "hsdshdflab.hdfgroup.org/groups/g-be6eb652-83c5-11e8-b9ee-0242ac12000a/links", "rel": "links"}, 122 | {"href": "hsdshdflab.hdfgroup.org/groups/g-be5996fa-83c5-11e8-a8e6-0242ac120016", "rel": "root"}, 123 | {"href": "hsdshdflab.hdfgroup.org/", "rel": "home"}, 124 | {"href": "hsdshdflab.hdfgroup.org/groups/g-be6eb652-83c5-11e8-b9ee-0242ac12000a/attributes", "rel": "attributes"} 125 | ] 126 | } 127 | ``` 128 | 129 | Related Resources 130 | ----------------- 131 | 132 | - DELETE\_Group 133 | - GET\_Links 134 | - GET\_Groups 135 | - POST\_Group 136 | - ../AttrOps/GET\_Attribute 137 | 138 | -------------------------------------------------------------------------------- /DatatypeOps/GET_Datatype.md: -------------------------------------------------------------------------------- 1 | GET Datatype 2 | ============ 3 | 4 | Description 5 | ----------- 6 | 7 | Returns information about the committed datatype with the UUID given in the URI. 8 | 9 | Requests 10 | -------- 11 | 12 | ### Syntax 13 | 14 | ``` sourceCode 15 | GET /datatypes/ HTTP/1.1 16 | X-Hdf-domain: DOMAIN 17 | Authorization: 18 | ``` 19 | 20 | ``` sourceCode 21 | GET /datatypes/?domain=DOMAIN HTTP/1.1 22 | Authorization: 23 | ``` 24 | 25 | *<id>* is the UUID of the requested datatype. 26 | 27 | ### Request Parameters 28 | 29 | This implementation of the operation does not use request parameters. 30 | 31 | ### Request Headers 32 | 33 | This implementation of the operation uses only the request headers that are common to most requests. See ../CommonRequestHeaders 34 | 35 | Responses 36 | --------- 37 | 38 | ### Response Headers 39 | 40 | This implementation of the operation uses only response headers that are common to most responses. See ../CommonResponseHeaders. 41 | 42 | ### Response Elements 43 | 44 | On success, a JSON response will be returned with the following elements: 45 | 46 | #### id 47 | 48 | The UUID of the datatype object. 49 | 50 | #### root 51 | 52 | The root group of the domain which the datatype is within. 53 | 54 | #### type 55 | 56 | A JSON object representing the type of the datatype object. 57 | 58 | #### attributeCount 59 | 60 | The number of attributes belonging to the datatype. 61 | 62 | #### created 63 | 64 | A timestamp giving the time the datatype was created in UTC (ISO-8601 format). 65 | 66 | #### lastModified 67 | 68 | A timestamp giving the most recent time the datatype has been modified (i.e. attributes updated) in UTC (ISO-8601 format). 69 | 70 | #### hrefs 71 | 72 | An array of links to related resources. See ../Hypermedia. 73 | 74 | ### Special Errors 75 | 76 | This implementation of the operation does not return special errors. For general information on standard error codes, see ../CommonErrorResponses. 77 | 78 | Examples 79 | -------- 80 | 81 | Get the committed datatype with UUID: "t-3e37ab7e-...". 82 | 83 | ### Sample Request 84 | 85 | ``` sourceCode 86 | GET /datatypes/t-3e37ab7e-86b3-11e8-bce3-0242ac12000c HTTP/1.1 87 | Host: hsdshdflab.hdfgroup.org 88 | X-Hdf-domain: /shared/tall.h5 89 | Accept-Encoding: gzip, deflate 90 | Accept: */* 91 | ``` 92 | 93 | ### Sample cURL command 94 | 95 | ``` sourceCode 96 | $ curl -X GET --header "X-Hdf-domain: /shared/tall.h5" hsdshdflab.hdfgroup.org/datatypes/t-3e37ab7e-86b3-11e8-bce3-0242ac12000c 97 | ``` 98 | 99 | ### Sample Response 100 | 101 | ``` sourceCode 102 | HTTP/1.1 200 OK 103 | Date: Fri, 13 Jul 2018 15:57:37 GMT 104 | Content-Length: 602 105 | Etag: "c53bc5b2d3c3b5059b71ef92ca7d144a2df54456" 106 | Content-Type: application/json 107 | Server: nginx/1.15.0 108 | ``` 109 | 110 | ``` sourceCode 111 | { 112 | "id": "t-3e37ab7e-86b3-11e8-bce3-0242ac12000c", 113 | "root": "g-b116b6f0-85e9-11e8-9cc2-0242ac120008", 114 | "domain": "/shared/tall.h5", 115 | "type": { 116 | "class": "H5T_FLOAT", 117 | "base": "H5T_IEEE_F64LE" 118 | }, 119 | "attributeCount": 0, 120 | "created": 1531496503.6064572, 121 | "lastModified": 1531496503.6064572, 122 | "hrefs": [ 123 | {"rel": "self", "href": "hsdshdflab.hdfgroup.org/datatypes/t-3e37ab7e-86b3-11e8-bce3-0242ac12000c"}, 124 | {"rel": "root", "href": "hsdshdflab.hdfgroup.org/groups/g-b116b6f0-85e9-11e8-9cc2-0242ac120008"}, 125 | {"rel": "home", "href": "hsdshdflab.hdfgroup.org/"}, 126 | {"rel": "attributes", "href": "hsdshdflab.hdfgroup.org/datatypes/t-3e37ab7e-86b3-11e8-bce3-0242ac12000c/attributes"} 127 | ] 128 | } 129 | ``` 130 | 131 | Related Resources 132 | ----------------- 133 | 134 | - DELETE\_Datatype 135 | - GET\_Datatypes 136 | - POST\_Datatype 137 | - ../DatasetOps/POST\_Dataset 138 | - ../AttrOps/PUT\_Attribute 139 | 140 | -------------------------------------------------------------------------------- /DomainOps/GET_Domain.md: -------------------------------------------------------------------------------- 1 | GET Domain 2 | ========== 3 | 4 | Description 5 | ----------- 6 | 7 | This operation retrieves information about the requested domain. 8 | 9 | *Note:* If the HDF Dynamic DNS Server (see ) is running, the operations can specify the domain as part of the URI. Example: returns data about the domain "tall" hosted on data.hdfgroup.org. The DNS server will determine the proper IP that maps to this domain. 10 | 11 | If the DNS Server is not setup, specify the desired domain in the "X-Hdf-domain" line of the http header. 12 | 13 | Alternatively, the domain can be specified as a query parameter. Example: 14 | 15 | . 16 | 17 | If no X-Hdf-domain value is supplied, the default Table of Contents (TOC) domain is returned. 18 | 19 | Requests 20 | -------- 21 | 22 | ### Syntax 23 | 24 | ``` sourceCode 25 | GET / HTTP/1.1 26 | X-Hdf-domain: DOMAIN 27 | Authorization: 28 | ``` 29 | 30 | ``` sourceCode 31 | GET /?domain=DOMAIN HTTP/1.1 32 | Authorization: 33 | ``` 34 | 35 | ### Request Parameters 36 | 37 | This implementation of the operation does not use request parameters. 38 | 39 | ### Request Headers 40 | 41 | This implementation of the operation uses only the request headers that are common to most requests. See ../CommonRequestHeaders 42 | 43 | Responses 44 | --------- 45 | 46 | ### Response Headers 47 | 48 | This implementation of the operation uses only response headers that are common to most responses. See ../CommonResponseHeaders. 49 | 50 | ### Response Elements 51 | 52 | On success, a JSON response will be returned with the following elements: 53 | 54 | #### root 55 | 56 | The UUID of the root group of this domain. 57 | 58 | #### created 59 | 60 | A timestamp giving the time the domain was created in UTC (ISO-8601 format). 61 | 62 | #### owner 63 | 64 | The user which owns the domain. 65 | 66 | #### lastModified 67 | 68 | A timestamp giving the most recent time that any content in the domain has been modified in UTC (ISO-8601 format). 69 | 70 | #### hrefs 71 | 72 | An array of links to related resources. See ../Hypermedia. 73 | 74 | ### Special Errors 75 | 76 | This implementation of the operation does not return any special errors. For general information on standard error codes, see ../CommonErrorResponses. 77 | 78 | Examples 79 | -------- 80 | 81 | ### Sample Request 82 | 83 | ``` sourceCode 84 | GET / HTTP/1.1 85 | Host: hsdshdflab.hdfgroup.org 86 | X-Hdf-domain: /shared/tall.h5 87 | Accept-Encoding: gzip, deflate 88 | Accept: */* 89 | ``` 90 | 91 | ### Sample cURL command 92 | 93 | ``` sourceCode 94 | $ curl -X GET --header "X-Hdf-domain: /shared/tall.h5" hsdshdflab.hdfgroup.org/ 95 | ``` 96 | 97 | ### Sample Response 98 | 99 | ``` sourceCode 100 | HTTP/1.1 200 OK 101 | Date: Thu, 12 Jul 2018 16:08:23 GMT 102 | Content-Length: 638 103 | Etag: "e45bef255ffc0530c33857b88b15f551f371de38" 104 | Content-Type: application/json 105 | Server: nginx/1.15.0 106 | ``` 107 | 108 | ``` sourceCode 109 | { 110 | "root": "g-be5996fa-83c5-11e8-a8e6-0242ac120016", 111 | "created": 1531174596.0696847, 112 | "owner": "admin", 113 | "class": "domain", 114 | "lastModified": 1531174596.0696847, 115 | "hrefs": [ 116 | {"href": "hsdshdflab.hdfgroup.org/", "rel": "self"}, 117 | {"href": "hsdshdflab.hdfgroup.org/datasets", "rel": "database"}, 118 | {"href": "hsdshdflab.hdfgroup.org/groups", "rel": "groupbase"}, 119 | {"href": "hsdshdflab.hdfgroup.org/datatypes", "rel": "typebase"}, 120 | {"href": "hsdshdflab.hdfgroup.org/groups/g-be5996fa-83c5-11e8-a8e6-0242ac120016", "rel": "root"}, 121 | {"href": "hsdshdflab.hdfgroup.org/acls", "rel": "acls"}, 122 | {"href": "hsdshdflab.hdfgroup.org/?domain=/shared", "rel": "parent"} 123 | ] 124 | } 125 | ``` 126 | 127 | Related Resources 128 | ----------------- 129 | 130 | - DELETE\_Domain 131 | - ../GroupOps/GET\_Group 132 | - PUT\_Domain 133 | 134 | -------------------------------------------------------------------------------- /AclOps/PUT_ACL.md: -------------------------------------------------------------------------------- 1 | PUT ACL 2 | ======= 3 | 4 | Description 5 | ----------- 6 | 7 | Update the access information for the given user for the object with the UUID provided in the URI. 8 | 9 | Requests 10 | -------- 11 | 12 | ### Syntax 13 | 14 | To update a user's access information for a domain: 15 | 16 | ``` sourceCode 17 | PUT /acls/ HTTP/1.1 18 | Host: DOMAIN 19 | Authorization: 20 | ``` 21 | 22 | To update a user's access information for a group: 23 | 24 | ``` sourceCode 25 | PUT /groups//acls/ HTTP/1.1 26 | Host: DOMAIN 27 | Authorization: 28 | ``` 29 | 30 | To get a user's access information for a dataset: 31 | 32 | ``` sourceCode 33 | PUT /datasets//acls/ HTTP/1.1 34 | Host: DOMAIN 35 | Authorization: 36 | ``` 37 | 38 | To get a user's access information for a committed datatype: 39 | 40 | ``` sourceCode 41 | PUT /datatypes//acls/ HTTP/1.1 42 | Host: DOMAIN 43 | Authorization: 44 | ``` 45 | 46 | where: 47 | 48 | - <id> is the UUID of the requested dataset/group/committed datatype 49 | - <userid> is the userid for the requested user. Use the special userid "default" to get the default access permisions for the object 50 | 51 | ### Request Parameters 52 | 53 | This implementation of the operation does not use request parameters. 54 | 55 | ### Request Headers 56 | 57 | This implementation of the operation uses only the request headers that are common to most requests. See ../CommonRequestHeaders 58 | 59 | ### Request Elements 60 | 61 | The request body most include a JSON object that has the following keys and boolean values: 62 | 63 | > { 'read': <True or False>, 64 | > 65 | > 'create': <True or False>, 66 | > 67 | > 'update': <True or False>, 68 | > 69 | > 'delete': <True or False>, 70 | > 71 | > 'readACL': <True or False>, 72 | > 73 | > 'updateACL': <True or False> 74 | > 75 | > } 76 | 77 | Responses 78 | --------- 79 | 80 | ### Response Headers 81 | 82 | This implementation of the operation uses only response headers that are common to most responses. See ../CommonResponseHeaders. 83 | 84 | ### Response Elements 85 | 86 | On success, a JSON response will be returned with the following elements: 87 | 88 | #### hrefs 89 | 90 | An array of hypertext links to related resources. See ../Hypermedia. 91 | 92 | ### Special Errors 93 | 94 | This implementation of the operation does not return special errors. For general information on standard error codes, see ../CommonErrorResponses. 95 | 96 | Examples 97 | -------- 98 | 99 | ### Sample Request 100 | 101 | ``` sourceCode 102 | PUT /groups/052dcbbd-9d33-11e4-86ce-3c15c2da029e/acls/test_user1 HTTP/1.1 103 | host: tall.test.hdfgroup.org 104 | Accept-Encoding: gzip, deflate 105 | Accept: */* 106 | User-Agent: python-requests/2.3.0 CPython/2.7.8 Darwin/14.0.0 107 | 108 | { 'read': True, 'create': False, 'update': False, 109 | 'delete': False, 'readACL': False, 'updateACL': False } 110 | ``` 111 | 112 | ### Sample Response 113 | 114 | ``` sourceCode 115 | HTTP/1.1 201 Created 116 | Date: Fri, 16 Jan 2015 20:06:08 GMT 117 | Content-Length: 660 118 | Etag: "2c410d1c469786f25ed0075571a8e7a3f313cec1" 119 | Content-Type: application/json 120 | Server: TornadoServer/3.2.2 121 | ``` 122 | 123 | ``` sourceCode 124 | "hrefs": [ 125 | { 126 | "href": "http://tall_acl.test.hdfgroup.org/groups/eb8f6959-8775-11e5-96b6-3c15c2da029e/acls/test_user1", 127 | "rel": "self" 128 | }, 129 | { 130 | "href": "http://tall_acl.test.hdfgroup.org/groups/eb8f6959-8775-11e5-96b6-3c15c2da029e", 131 | "rel": "root" 132 | }, 133 | { 134 | "href": "http://tall_acl.test.hdfgroup.org/", 135 | "rel": "home" 136 | }, 137 | { 138 | "href": "http://tall_acl.test.hdfgroup.org/groups/eb8f6959-8775-11e5-96b6-3c15c2da029e", 139 | "rel": "owner" 140 | } 141 | ] 142 | ``` 143 | 144 | Related Resources 145 | ----------------- 146 | 147 | - GET\_ACL 148 | - GET\_ACLs 149 | 150 | -------------------------------------------------------------------------------- /DatasetOps/GET_Datasets.md: -------------------------------------------------------------------------------- 1 | GET Datasets 2 | ============ 3 | 4 | Description 5 | ----------- 6 | 7 | Returns UUIDs for all the datasets in a domain. 8 | 9 | Requests 10 | -------- 11 | 12 | ### Syntax 13 | 14 | ``` sourceCode 15 | GET /datasets HTTP/1.1 16 | Host: DOMAIN 17 | Authorization: 18 | ``` 19 | 20 | ### Request Parameters 21 | 22 | This implementation of the operation uses the following request parameters (both optional): 23 | 24 | #### Limit 25 | 26 | If provided, a positive integer value specifying the maximum number of UUIDs to return. 27 | 28 | #### Marker 29 | 30 | If provided, a string value indicating that only UUIDs that occur after the marker value will be returned. 31 | 32 | ### Request Headers 33 | 34 | This implementation of the operation uses only the request headers that are common to most requests. See ../CommonRequestHeaders 35 | 36 | Responses 37 | --------- 38 | 39 | ### Response Headers 40 | 41 | This implementation of the operation uses only response headers that are common to most responses. See ../CommonResponseHeaders. 42 | 43 | ### Response Elements 44 | 45 | On success, a JSON response will be returned with the following elements: 46 | 47 | #### datasets 48 | 49 | An array of UUIDs, one for each dataset in the domain. 50 | 51 | #### hrefs 52 | 53 | An array of links to related resources. See ../Hypermedia. 54 | 55 | ### Special Errors 56 | 57 | This implementation of the operation does not return special errors. For general information on standard error codes, see ../CommonErrorResponses. 58 | 59 | Examples 60 | -------- 61 | 62 | ### Sample Request 63 | 64 | ``` sourceCode 65 | GET /datasets HTTP/1.1 66 | host: tall.test.hdfgroup.org 67 | Accept-Encoding: gzip, deflate 68 | Accept: */* 69 | User-Agent: python-requests/2.3.0 CPython/2.7.8 Darwin/14.0.0 70 | ``` 71 | 72 | ### Sample Response 73 | 74 | ``` sourceCode 75 | HTTP/1.1 200 OK 76 | Date: Fri, 23 Jan 2015 06:33:36 GMT 77 | Content-Length: 413 78 | Etag: "977e96c7bc63a6e05d10d56565df2ab8d30e404d" 79 | Content-Type: application/json 80 | Server: TornadoServer/3.2.2 81 | ``` 82 | 83 | ``` sourceCode 84 | { 85 | "datasets": [ 86 | "c8d7dd14-a2c6-11e4-a68c-3c15c2da029e", 87 | "c8d7f159-a2c6-11e4-99af-3c15c2da029e", 88 | "c8d83759-a2c6-11e4-8713-3c15c2da029e", 89 | "c8d84a8a-a2c6-11e4-b457-3c15c2da029e" 90 | ], 91 | "hrefs": [ 92 | {"href": "http://tall.test.hdfgroup.org/datasets", "rel": "self"}, 93 | {"href": "http://tall.test.hdfgroup.org/groups/c8d7842b-a2c6-11e4-b4f1-3c15c2da029e", "rel": "root"}, 94 | {"href": "http://tall.test.hdfgroup.org/", "rel": "home"} 95 | ] 96 | } 97 | ``` 98 | 99 | ### Sample Request with Marker and Limit 100 | 101 | This example uses the "Marker" request parameter to return only UUIDs after the given Marker value. The "Limit" request parameter is used to limit the number of UUIDs in the response to 5. 102 | 103 | ``` sourceCode 104 | GET /datasets?Marker=817db263-a2cc-11e4-87f2-3c15c2da029e&Limit=5 HTTP/1.1 105 | host: dset1k.test.hdfgroup.org 106 | Accept-Encoding: gzip, deflate 107 | Accept: */* 108 | User-Agent: python-requests/2.3.0 CPython/2.7.8 Darwin/14.0.0 109 | ``` 110 | 111 | ### Sample Response with Marker and Limit 112 | 113 | ``` sourceCode 114 | HTTP/1.1 200 OK 115 | Date: Fri, 23 Jan 2015 06:53:52 GMT 116 | Content-Length: 459 117 | Etag: "cb708d4839cc1e165fe6bb30718e49589ef140f4" 118 | Content-Type: application/json 119 | Server: TornadoServer/3.2.2 120 | ``` 121 | 122 | ``` sourceCode 123 | { 124 | "datasets": [ 125 | "817dcfb8-a2cc-11e4-9197-3c15c2da029e", 126 | "817de9ee-a2cc-11e4-8378-3c15c2da029e", 127 | "817e028a-a2cc-11e4-8ce3-3c15c2da029e", 128 | "817e1b61-a2cc-11e4-ba39-3c15c2da029e", 129 | "817e341c-a2cc-11e4-a16f-3c15c2da029e" 130 | ], 131 | "hrefs": [ 132 | {"href": "http://dset1k.test.hdfgroup.org/datasets", "rel": "self"}, 133 | {"href": "http://dset1k.test.hdfgroup.org/groups/81760a80-a2cc-11e4-bb55-3c15c2da029e", "rel": "root"}, 134 | {"href": "http://dset1k.test.hdfgroup.org/", "rel": "home"} 135 | ] 136 | } 137 | ``` 138 | 139 | Related Resources 140 | ----------------- 141 | 142 | - DELETE\_Dataset 143 | - GET\_Dataset 144 | - POST\_Dataset 145 | 146 | -------------------------------------------------------------------------------- /DatasetOps/GET_Dataset.md: -------------------------------------------------------------------------------- 1 | GET Dataset 2 | =========== 3 | 4 | Description 5 | ----------- 6 | 7 | Returns information about the dataset with the UUID given in the URI. 8 | 9 | Requests 10 | -------- 11 | 12 | ### Syntax 13 | 14 | ``` sourceCode 15 | GET /datasets/ HTTP/1.1 16 | Host: DOMAIN 17 | Authorization: 18 | ``` 19 | 20 | **<id>** is the UUID of the requested dataset. 21 | 22 | ### Request Parameters 23 | 24 | This implementation of the operation does not use request parameters. 25 | 26 | ### Request Headers 27 | 28 | This implementation of the operation uses only the request headers that are common to most requests. See ../CommonRequestHeaders 29 | 30 | Responses 31 | --------- 32 | 33 | ### Response Headers 34 | 35 | This implementation of the operation uses only response headers that are common to most responses. See ../CommonResponseHeaders. 36 | 37 | ### Response Elements 38 | 39 | On success, a JSON response will be returned with the following elements: 40 | 41 | #### id 42 | 43 | The UUID of the dataset object. 44 | 45 | #### type 46 | 47 | A JSON object representing the type of the dataset. See ../Types/index for details of the type representation. 48 | 49 | #### shape 50 | 51 | A JSON object representing the shape of the dataset. See GET\_DatasetShape for details of the shape representation. 52 | 53 | #### creationProperties 54 | 55 | A JSON object that describes chunk layout, filters, fill value, and other aspects of the dataset. See: for a complete description of fields that can be used. 56 | 57 | #### attributeCount 58 | 59 | The number of attributes belonging to the dataset. 60 | 61 | #### created 62 | 63 | A timestamp giving the time the dataset was created in UTC (ISO-8601 format). 64 | 65 | #### lastModified 66 | 67 | A timestamp giving the most recent time the group has been modified (i.e. attributes or links updated) in UTC (ISO-8601 format). 68 | 69 | #### hrefs 70 | 71 | An array of links to related resources. See ../Hypermedia. 72 | 73 | ### Special Errors 74 | 75 | This implementation of the operation does not return special errors. For general information on standard error codes, see ../CommonErrorResponses. 76 | 77 | Examples 78 | -------- 79 | 80 | ### Sample Request 81 | 82 | ``` sourceCode 83 | GET /datasets/c8d83759-a2c6-11e4-8713-3c15c2da029e HTTP/1.1 84 | host: tall.test.hdfgroup.org 85 | Accept-Encoding: gzip, deflate 86 | Accept: */* 87 | User-Agent: python-requests/2.3.0 CPython/2.7.8 Darwin/14.0.0 88 | ``` 89 | 90 | ### Sample Response 91 | 92 | ``` sourceCode 93 | HTTP/1.1 200 OK 94 | Date: Fri, 23 Jan 2015 06:15:33 GMT 95 | Content-Length: 755 96 | Etag: "ecbd7e52654b0a8f4ccbebac06175ce5df5f8c79" 97 | Content-Type: application/json 98 | Server: TornadoServer/3.2.2 99 | ``` 100 | 101 | ``` sourceCode 102 | { 103 | "id": "c8d83759-a2c6-11e4-8713-3c15c2da029e", 104 | "shape": { 105 | "dims": [10], 106 | "class": "H5S_SIMPLE" 107 | }, 108 | "type": { 109 | "base": "H5T_IEEE_F32BE", 110 | "class": "H5T_FLOAT" 111 | }, 112 | "creationProperties": { 113 | "allocTime": "H5D_ALLOC_TIME_LATE", 114 | "fillTime": "H5D_FILL_TIME_IFSET", 115 | "layout": { 116 | "class": "H5D_CONTIGUOUS" 117 | } 118 | }, 119 | "attributeCount": 0, 120 | "created": "2015-01-23T06:12:18Z", 121 | "lastModified": "2015-01-23T06:12:18Z", 122 | "hrefs": [ 123 | {"href": "http://tall.test.hdfgroup.org/datasets/c8d83759-a2c6-11e4-8713-3c15c2da029e", "rel": "self"}, 124 | {"href": "http://tall.test.hdfgroup.org/groups/c8d7842b-a2c6-11e4-b4f1-3c15c2da029e", "rel": "root"}, 125 | {"href": "http://tall.test.hdfgroup.org/datasets/c8d83759-a2c6-11e4-8713-3c15c2da029e/attributes", "rel": "attributes"}, 126 | {"href": "http://tall.test.hdfgroup.org/datasets/c8d83759-a2c6-11e4-8713-3c15c2da029e/value", "rel": "data"}, 127 | {"href": "http://tall.test.hdfgroup.org/", "rel": "home"} 128 | ] 129 | } 130 | ``` 131 | 132 | Related Resources 133 | ----------------- 134 | 135 | - DELETE\_Dataset 136 | - ../AttrOps/GET\_Attributes 137 | - GET\_DatasetShape 138 | - GET\_DatasetType 139 | - GET\_Datasets 140 | - GET\_Value 141 | - POST\_Value 142 | - PUT\_Value 143 | 144 | -------------------------------------------------------------------------------- /GroupOps/GET_Group.rst: -------------------------------------------------------------------------------- 1 | ********************************************** 2 | GET Group 3 | ********************************************** 4 | 5 | Description 6 | =========== 7 | Returns information about the group with the UUID given in the URI. 8 | 9 | Requests 10 | ======== 11 | 12 | Syntax 13 | ------ 14 | .. code-block:: http 15 | 16 | GET /groups/ HTTP/1.1 17 | X-Hdf-domain: DOMAIN 18 | Authorization: 19 | 20 | .. code-block:: http 21 | 22 | GET /groups/?domain=DOMAIN HTTP/1.1 23 | Authorization: 24 | 25 | ** is the UUID of the requested group. 26 | 27 | Request Parameters 28 | ------------------ 29 | 30 | include_links 31 | ^^^^^^^^^^^^^ 32 | 33 | If this request parameter is provided, the links of the group are included in the response. 34 | 35 | Request Headers 36 | --------------- 37 | This implementation of the operation uses only the request headers that are common 38 | to most requests. See :doc:`../CommonRequestHeaders` 39 | 40 | Responses 41 | ========= 42 | 43 | Response Headers 44 | ---------------- 45 | 46 | This implementation of the operation uses only response headers that are common to 47 | most responses. See :doc:`../CommonResponseHeaders`. 48 | 49 | Response Elements 50 | ----------------- 51 | 52 | On success, a JSON response will be returned with the following elements: 53 | 54 | id 55 | ^^ 56 | The UUID of the requested group. 57 | 58 | root 59 | ^^^^ 60 | The root group of the domain that the group is within. 61 | 62 | attributeCount 63 | ^^^^^^^^^^^^^^ 64 | The number of attributes belonging to the group. 65 | 66 | linkCount 67 | ^^^^^^^^^ 68 | The number of links belonging to the group. 69 | 70 | created 71 | ^^^^^^^ 72 | A timestamp giving the time the group was created in UTC (ISO-8601 format). 73 | 74 | lastModified 75 | ^^^^^^^^^^^^ 76 | A timestamp giving the most recent time the group has been modified (i.e. attributes or 77 | links updated) in UTC (ISO-8601 format). 78 | 79 | hrefs 80 | ^^^^^ 81 | An array of hypertext links to related resources. See :doc:`../Hypermedia`. 82 | 83 | Special Errors 84 | -------------- 85 | 86 | This implementation of the operation does not return special errors. For general 87 | information on standard error codes, see :doc:`../CommonErrorResponses`. 88 | 89 | Examples 90 | ======== 91 | 92 | Sample Request 93 | -------------- 94 | 95 | .. code-block:: http 96 | 97 | GET /groups/g-be6eb652-83c5-11e8-b9ee-0242ac12000a HTTP/1.1 98 | Host: hsdshdflab.hdfgroup.org 99 | X-Hdf-domain: /shared/tall.h5 100 | Accept-Encoding: gzip, deflate 101 | Accept: */* 102 | 103 | Sample cURL command 104 | ------------------- 105 | 106 | .. code-block:: bash 107 | 108 | $ curl -X GET --header "X-Hdf-domain: /shared/tall.h5" hsdshdflab.hdfgroup.org/groups/g-be6eb652-83c5-11e8-b9ee-0242ac12000a 109 | 110 | Sample Response 111 | --------------- 112 | 113 | .. code-block:: http 114 | 115 | HTTP/1.1 200 OK 116 | Date: Thu, 12 Jul 2018 18:27:24 GMT 117 | Content-Length: 711 118 | Etag: "2c410d1c469786f25ed0075571a8e7a3f313cec1" 119 | Content-Type: application/json 120 | Server: nginx/1.15.0 121 | 122 | .. code-block:: json 123 | 124 | { 125 | "id": "g-be6eb652-83c5-11e8-b9ee-0242ac12000a", 126 | "root": "g-be5996fa-83c5-11e8-a8e6-0242ac120016", 127 | "linkCount": 2, 128 | "attributeCount": 0, 129 | "lastModified": 1531174596.5785563, 130 | "created": 1531174596.2463753, 131 | "domain": "/shared/tall.h5", 132 | "hrefs": [ 133 | {"href": "hsdshdflab.hdfgroup.org/groups/g-be6eb652-83c5-11e8-b9ee-0242ac12000a", "rel": "self"}, 134 | {"href": "hsdshdflab.hdfgroup.org/groups/g-be6eb652-83c5-11e8-b9ee-0242ac12000a/links", "rel": "links"}, 135 | {"href": "hsdshdflab.hdfgroup.org/groups/g-be5996fa-83c5-11e8-a8e6-0242ac120016", "rel": "root"}, 136 | {"href": "hsdshdflab.hdfgroup.org/", "rel": "home"}, 137 | {"href": "hsdshdflab.hdfgroup.org/groups/g-be6eb652-83c5-11e8-b9ee-0242ac12000a/attributes", "rel": "attributes"} 138 | ] 139 | } 140 | 141 | Related Resources 142 | ================= 143 | 144 | * :doc:`DELETE_Group` 145 | * :doc:`GET_Links` 146 | * :doc:`GET_Groups` 147 | * :doc:`POST_Group` 148 | * :doc:`../AttrOps/GET_Attribute` 149 | 150 | 151 | -------------------------------------------------------------------------------- /DatatypeOps/GET_Datatype.rst: -------------------------------------------------------------------------------- 1 | ********************************************** 2 | GET Datatype 3 | ********************************************** 4 | 5 | Description 6 | =========== 7 | Returns information about the committed datatype with the UUID given in the URI. 8 | 9 | Requests 10 | ======== 11 | 12 | Syntax 13 | ------ 14 | .. code-block:: http 15 | 16 | GET /datatypes/ HTTP/1.1 17 | X-Hdf-domain: DOMAIN 18 | Authorization: 19 | 20 | .. code-block:: http 21 | 22 | GET /datatypes/?domain=DOMAIN HTTP/1.1 23 | Authorization: 24 | 25 | ** is the UUID of the requested datatype. 26 | 27 | Request Parameters 28 | ------------------ 29 | This implementation of the operation does not use request parameters. 30 | 31 | Request Headers 32 | --------------- 33 | This implementation of the operation uses only the request headers that are common 34 | to most requests. See :doc:`../CommonRequestHeaders` 35 | 36 | Responses 37 | ========= 38 | 39 | Response Headers 40 | ---------------- 41 | 42 | This implementation of the operation uses only response headers that are common to 43 | most responses. See :doc:`../CommonResponseHeaders`. 44 | 45 | Response Elements 46 | ----------------- 47 | 48 | On success, a JSON response will be returned with the following elements: 49 | 50 | id 51 | ^^ 52 | The UUID of the datatype object. 53 | 54 | root 55 | ^^^^ 56 | The root group of the domain which the datatype is within. 57 | 58 | type 59 | ^^^^ 60 | A JSON object representing the type of the datatype object. 61 | 62 | attributeCount 63 | ^^^^^^^^^^^^^^ 64 | The number of attributes belonging to the datatype. 65 | 66 | created 67 | ^^^^^^^ 68 | A timestamp giving the time the datatype was created in UTC (ISO-8601 format). 69 | 70 | lastModified 71 | ^^^^^^^^^^^^ 72 | A timestamp giving the most recent time the datatype has been modified (i.e. attributes updated) in UTC (ISO-8601 format). 73 | 74 | hrefs 75 | ^^^^^ 76 | An array of links to related resources. See :doc:`../Hypermedia`. 77 | 78 | Special Errors 79 | -------------- 80 | 81 | This implementation of the operation does not return special errors. For general 82 | information on standard error codes, see :doc:`../CommonErrorResponses`. 83 | 84 | Examples 85 | ======== 86 | 87 | Get the committed datatype with UUID: "t-3e37ab7e-...". 88 | 89 | Sample Request 90 | -------------- 91 | 92 | .. code-block:: http 93 | 94 | GET /datatypes/t-3e37ab7e-86b3-11e8-bce3-0242ac12000c HTTP/1.1 95 | Host: hsdshdflab.hdfgroup.org 96 | X-Hdf-domain: /shared/tall.h5 97 | Accept-Encoding: gzip, deflate 98 | Accept: */* 99 | 100 | Sample cURL command 101 | ------------------- 102 | 103 | .. code-block:: bash 104 | 105 | $ curl -X GET --header "X-Hdf-domain: /shared/tall.h5" hsdshdflab.hdfgroup.org/datatypes/t-3e37ab7e-86b3-11e8-bce3-0242ac12000c 106 | 107 | Sample Response 108 | --------------- 109 | 110 | .. code-block:: http 111 | 112 | HTTP/1.1 200 OK 113 | Date: Fri, 13 Jul 2018 15:57:37 GMT 114 | Content-Length: 602 115 | Etag: "c53bc5b2d3c3b5059b71ef92ca7d144a2df54456" 116 | Content-Type: application/json 117 | Server: nginx/1.15.0 118 | 119 | .. code-block:: json 120 | 121 | { 122 | "id": "t-3e37ab7e-86b3-11e8-bce3-0242ac12000c", 123 | "root": "g-b116b6f0-85e9-11e8-9cc2-0242ac120008", 124 | "domain": "/shared/tall.h5", 125 | "type": { 126 | "class": "H5T_FLOAT", 127 | "base": "H5T_IEEE_F64LE" 128 | }, 129 | "attributeCount": 0, 130 | "created": 1531496503.6064572, 131 | "lastModified": 1531496503.6064572, 132 | "hrefs": [ 133 | {"rel": "self", "href": "hsdshdflab.hdfgroup.org/datatypes/t-3e37ab7e-86b3-11e8-bce3-0242ac12000c"}, 134 | {"rel": "root", "href": "hsdshdflab.hdfgroup.org/groups/g-b116b6f0-85e9-11e8-9cc2-0242ac120008"}, 135 | {"rel": "home", "href": "hsdshdflab.hdfgroup.org/"}, 136 | {"rel": "attributes", "href": "hsdshdflab.hdfgroup.org/datatypes/t-3e37ab7e-86b3-11e8-bce3-0242ac12000c/attributes"} 137 | ] 138 | } 139 | 140 | 141 | Related Resources 142 | ================= 143 | 144 | * :doc:`DELETE_Datatype` 145 | * :doc:`GET_Datatypes` 146 | * :doc:`POST_Datatype` 147 | * :doc:`../DatasetOps/POST_Dataset` 148 | * :doc:`../AttrOps/PUT_Attribute` 149 | 150 | 151 | -------------------------------------------------------------------------------- /AclOps/GET_ACL.md: -------------------------------------------------------------------------------- 1 | GET ACL 2 | ======= 3 | 4 | Description 5 | ----------- 6 | 7 | Returns access information for the given user for the object with the UUID provided in the URI. 8 | 9 | Requests 10 | -------- 11 | 12 | ### Syntax 13 | 14 | To get a user's default access for a domain: 15 | 16 | ``` sourceCode 17 | GET /acls/ HTTP/1.1 18 | Host: DOMAIN 19 | Authorization: 20 | ``` 21 | 22 | To get a user's access information for a group: 23 | 24 | ``` sourceCode 25 | GET /groups//acls/ HTTP/1.1 26 | Host: DOMAIN 27 | Authorization: 28 | ``` 29 | 30 | To get a user's access information for a dataset: 31 | 32 | ``` sourceCode 33 | GET /datasets//acls/ HTTP/1.1 34 | Host: DOMAIN 35 | Authorization: 36 | ``` 37 | 38 | To get a user's access information for a committed datatype: 39 | 40 | ``` sourceCode 41 | GET /datatypes//acls/ HTTP/1.1 42 | Host: DOMAIN 43 | Authorization: 44 | ``` 45 | 46 | where: 47 | 48 | - <id> is the UUID of the requested dataset/group/committed datatype 49 | - <userid> is the userid for the requested user. Use the special userid "default" to get the default access permisions for the object 50 | 51 | ### Request Parameters 52 | 53 | This implementation of the operation does not use request parameters. 54 | 55 | ### Request Headers 56 | 57 | This implementation of the operation uses only the request headers that are common to most requests. See ../CommonRequestHeaders 58 | 59 | Responses 60 | --------- 61 | 62 | ### Response Headers 63 | 64 | This implementation of the operation uses only response headers that are common to most responses. See ../CommonResponseHeaders. 65 | 66 | ### Response Elements 67 | 68 | On success, a JSON response will be returned with the following elements: 69 | 70 | #### acl 71 | 72 | A JSON object that describes a user's access permissions. Subkeys of acl are: 73 | 74 | userName: the userid of the requested user 75 | 76 | create: A boolean flag that indicates if the user is authorized to create new resources 77 | 78 | delete: A boolean flag that indicates if the user is authorized to delete resources 79 | 80 | read: A boolean flag that indicates if the user is authorized to read (GET) resources 81 | 82 | update: A boolean flag that indicates if the user is authorized to update resources 83 | 84 | readACL: A boolean flag that indicates if the user is authorized to read the object's ACL 85 | 86 | updateACL: A boolean flag that indicates if the user is authorized to update the object's ACL 87 | 88 | #### hrefs 89 | 90 | An array of hypertext links to related resources. See ../Hypermedia. 91 | 92 | ### Special Errors 93 | 94 | This implementation of the operation does not return special errors. For general information on standard error codes, see ../CommonErrorResponses. 95 | 96 | Examples 97 | -------- 98 | 99 | ### Sample Request 100 | 101 | ``` sourceCode 102 | GET /groups/052dcbbd-9d33-11e4-86ce-3c15c2da029e/acls/test_user1 HTTP/1.1 103 | host: tall.test.hdfgroup.org 104 | Accept-Encoding: gzip, deflate 105 | Accept: */* 106 | User-Agent: python-requests/2.3.0 CPython/2.7.8 Darwin/14.0.0 107 | ``` 108 | 109 | ### Sample Response 110 | 111 | ``` sourceCode 112 | HTTP/1.1 200 OK 113 | Date: Fri, 16 Jan 2015 20:06:08 GMT 114 | Content-Length: 660 115 | Etag: "2c410d1c469786f25ed0075571a8e7a3f313cec1" 116 | Content-Type: application/json 117 | Server: TornadoServer/3.2.2 118 | ``` 119 | 120 | ``` sourceCode 121 | { 122 | "acl": { 123 | "create": false, 124 | "delete": false, 125 | "read": true, 126 | "readACL": false, 127 | "update": false, 128 | "updateACL": false, 129 | "userName": "test_user1" 130 | }, 131 | "hrefs": [ 132 | { 133 | "href": "http://tall_acl.test.hdfgroup.org/groups/eb8f6959-8775-11e5-96b6-3c15c2da029e/acls/test_user1", 134 | "rel": "self" 135 | }, 136 | { 137 | "href": "http://tall_acl.test.hdfgroup.org/groups/eb8f6959-8775-11e5-96b6-3c15c2da029e", 138 | "rel": "root" 139 | }, 140 | { 141 | "href": "http://tall_acl.test.hdfgroup.org/", 142 | "rel": "home" 143 | }, 144 | { 145 | "href": "http://tall_acl.test.hdfgroup.org/groups/eb8f6959-8775-11e5-96b6-3c15c2da029e", 146 | "rel": "owner" 147 | } 148 | ] 149 | ``` 150 | 151 | Related Resources 152 | ----------------- 153 | 154 | - PUT\_ACL 155 | - GET\_ACLs 156 | 157 | -------------------------------------------------------------------------------- /DomainOps/GET_Domain.rst: -------------------------------------------------------------------------------- 1 | ********************************************** 2 | GET Domain 3 | ********************************************** 4 | 5 | Description 6 | =========== 7 | This operation retrieves information about the requested domain. 8 | 9 | *Note:* If the HDF Dynamic DNS Server (see https://github.com/HDFGroup/dynamic-dns) is running, 10 | the operations can specify the domain as part of the URI. Example: 11 | http://tall.data.hdfgroup.org:7253/ 12 | returns data about the domain "tall" hosted on data.hdfgroup.org. 13 | The DNS server will determine the proper IP that maps to this domain. 14 | 15 | If the DNS Server is not setup, specify the desired domain in the "X-Hdf-domain" line of the http 16 | header. 17 | 18 | Alternatively, the domain can be specified as a query parameter. Example: 19 | 20 | http://127.0.0.1:7253?domain=tall.data.hdfgroup.org. 21 | 22 | If no X-Hdf-domain value is supplied, the default Table of Contents (TOC) domain is returned. 23 | 24 | Requests 25 | ======== 26 | 27 | Syntax 28 | ------ 29 | .. code-block:: http 30 | 31 | GET / HTTP/1.1 32 | X-Hdf-domain: DOMAIN 33 | Authorization: 34 | 35 | .. code-block:: http 36 | 37 | GET /?domain=DOMAIN HTTP/1.1 38 | Authorization: 39 | 40 | Request Parameters 41 | ------------------ 42 | This implementation of the operation does not use request parameters. 43 | 44 | Request Headers 45 | --------------- 46 | This implementation of the operation uses only the request headers that are common 47 | to most requests. See :doc:`../CommonRequestHeaders` 48 | 49 | Responses 50 | ========= 51 | 52 | Response Headers 53 | ---------------- 54 | 55 | This implementation of the operation uses only response headers that are common to 56 | most responses. See :doc:`../CommonResponseHeaders`. 57 | 58 | Response Elements 59 | ----------------- 60 | 61 | On success, a JSON response will be returned with the following elements: 62 | 63 | root 64 | ^^^^ 65 | The UUID of the root group of this domain. 66 | 67 | created 68 | ^^^^^^^ 69 | A timestamp giving the time the domain was created in UTC (ISO-8601 format). 70 | 71 | owner 72 | ^^^^^ 73 | The user which owns the domain. 74 | 75 | lastModified 76 | ^^^^^^^^^^^^ 77 | A timestamp giving the most recent time that any content in the domain has been 78 | modified in UTC (ISO-8601 format). 79 | 80 | hrefs 81 | ^^^^^ 82 | An array of links to related resources. See :doc:`../Hypermedia`. 83 | 84 | Special Errors 85 | -------------- 86 | 87 | This implementation of the operation does not return any special errors. For general 88 | information on standard error codes, see :doc:`../CommonErrorResponses`. 89 | 90 | Examples 91 | ======== 92 | 93 | Sample Request 94 | -------------- 95 | 96 | .. code-block:: http 97 | 98 | GET / HTTP/1.1 99 | Host: hsdshdflab.hdfgroup.org 100 | X-Hdf-domain: /shared/tall.h5 101 | Accept-Encoding: gzip, deflate 102 | Accept: */* 103 | 104 | Sample cURL command 105 | ------------------- 106 | 107 | .. code-block:: bash 108 | 109 | $ curl -X GET --header "X-Hdf-domain: /shared/tall.h5" hsdshdflab.hdfgroup.org/ 110 | 111 | Sample Response 112 | --------------- 113 | 114 | .. code-block:: http 115 | 116 | HTTP/1.1 200 OK 117 | Date: Thu, 12 Jul 2018 16:08:23 GMT 118 | Content-Length: 638 119 | Etag: "e45bef255ffc0530c33857b88b15f551f371de38" 120 | Content-Type: application/json 121 | Server: nginx/1.15.0 122 | 123 | .. code-block:: json 124 | 125 | { 126 | "root": "g-be5996fa-83c5-11e8-a8e6-0242ac120016", 127 | "created": 1531174596.0696847, 128 | "owner": "admin", 129 | "class": "domain", 130 | "lastModified": 1531174596.0696847, 131 | "hrefs": [ 132 | {"href": "hsdshdflab.hdfgroup.org/", "rel": "self"}, 133 | {"href": "hsdshdflab.hdfgroup.org/datasets", "rel": "database"}, 134 | {"href": "hsdshdflab.hdfgroup.org/groups", "rel": "groupbase"}, 135 | {"href": "hsdshdflab.hdfgroup.org/datatypes", "rel": "typebase"}, 136 | {"href": "hsdshdflab.hdfgroup.org/groups/g-be5996fa-83c5-11e8-a8e6-0242ac120016", "rel": "root"}, 137 | {"href": "hsdshdflab.hdfgroup.org/acls", "rel": "acls"}, 138 | {"href": "hsdshdflab.hdfgroup.org/?domain=/shared", "rel": "parent"} 139 | ] 140 | } 141 | 142 | Related Resources 143 | ================= 144 | 145 | * :doc:`DELETE_Domain` 146 | * :doc:`../GroupOps/GET_Group` 147 | * :doc:`PUT_Domain` 148 | 149 | 150 | -------------------------------------------------------------------------------- /AclOps/PUT_ACL.rst: -------------------------------------------------------------------------------- 1 | ********************************************** 2 | PUT ACL 3 | ********************************************** 4 | 5 | Description 6 | =========== 7 | Update the access information for the given user for the object with the UUID provided in the URI. 8 | 9 | Requests 10 | ======== 11 | 12 | Syntax 13 | ------ 14 | 15 | To update a user's access information for a domain: 16 | 17 | .. code-block:: http 18 | 19 | PUT /acls/ HTTP/1.1 20 | Host: DOMAIN 21 | Authorization: 22 | 23 | To update a user's access information for a group: 24 | 25 | .. code-block:: http 26 | 27 | PUT /groups//acls/ HTTP/1.1 28 | Host: DOMAIN 29 | Authorization: 30 | 31 | 32 | To get a user's access information for a dataset: 33 | 34 | .. code-block:: http 35 | 36 | PUT /datasets//acls/ HTTP/1.1 37 | Host: DOMAIN 38 | Authorization: 39 | 40 | 41 | To get a user's access information for a committed datatype: 42 | 43 | .. code-block:: http 44 | 45 | PUT /datatypes//acls/ HTTP/1.1 46 | Host: DOMAIN 47 | Authorization: 48 | 49 | where: 50 | 51 | * is the UUID of the requested dataset/group/committed datatype 52 | * is the userid for the requested user. Use the special userid "default" to get the default access permisions for the object 53 | 54 | Request Parameters 55 | ------------------ 56 | This implementation of the operation does not use request parameters. 57 | 58 | Request Headers 59 | --------------- 60 | This implementation of the operation uses only the request headers that are common 61 | to most requests. See :doc:`../CommonRequestHeaders` 62 | 63 | Request Elements 64 | ---------------- 65 | 66 | The request body most include a JSON object that has the following keys and boolean values: 67 | 68 | { 69 | 'read': , 70 | 71 | 'create': , 72 | 73 | 'update': , 74 | 75 | 'delete': , 76 | 77 | 'readACL': , 78 | 79 | 'updateACL': 80 | 81 | } 82 | 83 | Responses 84 | ========= 85 | 86 | Response Headers 87 | ---------------- 88 | 89 | This implementation of the operation uses only response headers that are common to 90 | most responses. See :doc:`../CommonResponseHeaders`. 91 | 92 | Response Elements 93 | ----------------- 94 | 95 | On success, a JSON response will be returned with the following elements: 96 | 97 | 98 | hrefs 99 | ^^^^^ 100 | An array of hypertext links to related resources. See :doc:`../Hypermedia`. 101 | 102 | Special Errors 103 | -------------- 104 | 105 | This implementation of the operation does not return special errors. For general 106 | information on standard error codes, see :doc:`../CommonErrorResponses`. 107 | 108 | Examples 109 | ======== 110 | 111 | Sample Request 112 | -------------- 113 | 114 | .. code-block:: http 115 | 116 | PUT /groups/052dcbbd-9d33-11e4-86ce-3c15c2da029e/acls/test_user1 HTTP/1.1 117 | host: tall.test.hdfgroup.org 118 | Accept-Encoding: gzip, deflate 119 | Accept: */* 120 | User-Agent: python-requests/2.3.0 CPython/2.7.8 Darwin/14.0.0 121 | 122 | { 'read': True, 'create': False, 'update': False, 123 | 'delete': False, 'readACL': False, 'updateACL': False } 124 | 125 | Sample Response 126 | --------------- 127 | 128 | .. code-block:: http 129 | 130 | HTTP/1.1 201 Created 131 | Date: Fri, 16 Jan 2015 20:06:08 GMT 132 | Content-Length: 660 133 | Etag: "2c410d1c469786f25ed0075571a8e7a3f313cec1" 134 | Content-Type: application/json 135 | Server: TornadoServer/3.2.2 136 | 137 | .. code-block:: json 138 | 139 | 140 | "hrefs": [ 141 | { 142 | "href": "http://tall_acl.test.hdfgroup.org/groups/eb8f6959-8775-11e5-96b6-3c15c2da029e/acls/test_user1", 143 | "rel": "self" 144 | }, 145 | { 146 | "href": "http://tall_acl.test.hdfgroup.org/groups/eb8f6959-8775-11e5-96b6-3c15c2da029e", 147 | "rel": "root" 148 | }, 149 | { 150 | "href": "http://tall_acl.test.hdfgroup.org/", 151 | "rel": "home" 152 | }, 153 | { 154 | "href": "http://tall_acl.test.hdfgroup.org/groups/eb8f6959-8775-11e5-96b6-3c15c2da029e", 155 | "rel": "owner" 156 | } 157 | ] 158 | 159 | Related Resources 160 | ================= 161 | 162 | * :doc:`GET_ACL` 163 | * :doc:`GET_ACLs` 164 | 165 | 166 | 167 | -------------------------------------------------------------------------------- /GroupOps/GET_Groups.md: -------------------------------------------------------------------------------- 1 | GET Groups 2 | ========== 3 | 4 | Description 5 | ----------- 6 | 7 | Returns UUIDs for all the groups in a domain (other than the root group). 8 | 9 | Requests 10 | -------- 11 | 12 | ### Syntax 13 | 14 | ``` sourceCode 15 | GET /groups HTTP/1.1 16 | X-Hdf-domain: DOMAIN 17 | Authorization: 18 | ``` 19 | 20 | ``` sourceCode 21 | GET /groups?domain=DOMAIN HTTP/1.1 22 | Authorization: 23 | ``` 24 | 25 | ### Request Parameters 26 | 27 | This implementation of the operation uses the following request parameters (both optional): 28 | 29 | #### Limit 30 | 31 | If provided, a positive integer value specifying the maximum number of UUIDs to return. 32 | 33 | #### Marker 34 | 35 | If provided, a string value indicating that only UUIDs that occur after the marker value will be returned. 36 | 37 | ### Request Headers 38 | 39 | This implementation of the operation uses only the request headers that are common to most requests. See ../CommonRequestHeaders 40 | 41 | Responses 42 | --------- 43 | 44 | ### Response Headers 45 | 46 | This implementation of the operation uses only response headers that are common to most responses. See ../CommonResponseHeaders. 47 | 48 | ### Response Elements 49 | 50 | On success, a JSON response will be returned with the following elements: 51 | 52 | #### groups 53 | 54 | An array of UUIDs - one for each group (excluding the root group) in the domain. If the "Marker" and/or "Limit" request parameters are used, a subset of the UUIDs may be returned. 55 | 56 | #### hrefs 57 | 58 | An array of hypertext links to related resources. See ../Hypermedia. 59 | 60 | ### Special Errors 61 | 62 | This implementation of the operation does not return special errors. For general information on standard error codes, see ../CommonErrorResponses. 63 | 64 | Examples 65 | -------- 66 | 67 | ### Sample Request 68 | 69 | ``` sourceCode 70 | GET /groups HTTP/1.1 71 | Host: hsdshdflab.hdfgroup.org 72 | X-Hdf-domain: /shared/tall.h5 73 | Accept-Encoding: gzip, deflate 74 | Accept: */* 75 | ``` 76 | 77 | ### Sample cURL command 78 | 79 | ``` sourceCode 80 | $ curl -X GET --header "X-Hdf-domain: /shared/tall.h5" hsdshdflab.hdfgroup.org/groups 81 | ``` 82 | 83 | ### Sample Response 84 | 85 | ``` sourceCode 86 | HTTP/1.1 200 OK 87 | Date: Thu, 12 Jul 2018 18:40:30 GMT 88 | Content-Length: 443 89 | Etag: "83575a7865761b6d4eaf5d285ab1de062c49250b" 90 | Content-Type: application/json 91 | Server: nginx/1.15.0 92 | ``` 93 | 94 | ``` sourceCode 95 | { 96 | "groups": [ 97 | "g-be6eb652-83c5-11e8-b9ee-0242ac12000a", 98 | "g-be836c0a-83c5-11e8-947e-0242ac120014", 99 | "g-beaaa824-83c5-11e8-a8e6-0242ac120016", 100 | "g-beb56bba-83c5-11e8-87e1-0242ac12000c", 101 | "g-bf15f8b8-83c5-11e8-8ad9-0242ac120009" 102 | ], 103 | "hrefs": [ 104 | {"href": "hsdshdflab.hdfgroup.org/groups", "rel": "self"}, 105 | {"href": "hsdshdflab.hdfgroup.org/groups/g-be5996fa-83c5-11e8-a8e6-0242ac120016", "rel": "root"}, 106 | {"href": "hsdshdflab.hdfgroup.org/", "rel": "home"} 107 | ] 108 | } 109 | ``` 110 | 111 | ### Sample Request with Marker and Limit 112 | 113 | This example uses the "Marker" request parameter to return only UUIDs after the given Marker value. The "Limit" request parameter is used to limit the number of UUIDs in the response to 2. 114 | 115 | ``` sourceCode 116 | GET /groups?Marker=g-be836c0a-83c5-11e8-947e-0242ac120014&Limit=2 HTTP/1.1 117 | Host: hsdshdflab.hdfgroup.org 118 | X-Hdf-domain: /shared/tall.h5 119 | Accept-Encoding: gzip, deflate 120 | Accept: */* 121 | ``` 122 | 123 | ### Sample cURL command 124 | 125 | *URL enclosed in quotes to prevent shell from seeing ampersand* 126 | 127 | ``` sourceCode 128 | $ curl -X GET --header "X-Hdf-domain: /shared/tall.h5" "hsdshdflab.hdfgroup.org/groups?Marker=g-be836c0a-83c5-11e8-947e-0242ac120014&Limit=2" 129 | ``` 130 | 131 | ### Sample Response with Marker and Limit 132 | 133 | ``` sourceCode 134 | HTTP/1.1 200 OK 135 | Date: Thu, 12 Jul 2018 18:52:35 GMT 136 | Content-Length: 317 137 | Etag: "49221af3436fdaca7e26c74b491ccf8698555f08" 138 | Content-Type: application/json 139 | Server: nginx/1.15.0 140 | ``` 141 | 142 | ``` sourceCode 143 | { 144 | "groups": [ 145 | "g-beaaa824-83c5-11e8-a8e6-0242ac120016", 146 | "g-beb56bba-83c5-11e8-87e1-0242ac12000c" 147 | ], 148 | "hrefs": [ 149 | {"href": "hsdshdflab.hdfgroup.org/groups", "rel": "self"}, 150 | {"href": "hsdshdflab.hdfgroup.org/groups/g-be5996fa-83c5-11e8-a8e6-0242ac120016", "rel": "root"}, 151 | {"href": "hsdshdflab.hdfgroup.org/", "rel": "home"} 152 | ] 153 | } 154 | ``` 155 | 156 | Related Resources 157 | ----------------- 158 | 159 | - DELETE\_Group 160 | - GET\_Links 161 | - GET\_Group 162 | - POST\_Group 163 | 164 | -------------------------------------------------------------------------------- /DatasetOps/GET_Dataset.rst: -------------------------------------------------------------------------------- 1 | ********************************************** 2 | GET Dataset 3 | ********************************************** 4 | 5 | Description 6 | =========== 7 | Returns information about the dataset with the UUID given in the URI. 8 | 9 | Requests 10 | ======== 11 | 12 | Syntax 13 | ------ 14 | .. code-block:: http 15 | 16 | GET /datasets/ HTTP/1.1 17 | Host: DOMAIN 18 | Authorization: 19 | 20 | **** is the UUID of the requested dataset. 21 | 22 | Request Parameters 23 | ------------------ 24 | This implementation of the operation does not use request parameters. 25 | 26 | Request Headers 27 | --------------- 28 | This implementation of the operation uses only the request headers that are common 29 | to most requests. See :doc:`../CommonRequestHeaders` 30 | 31 | Responses 32 | ========= 33 | 34 | Response Headers 35 | ---------------- 36 | 37 | This implementation of the operation uses only response headers that are common to 38 | most responses. See :doc:`../CommonResponseHeaders`. 39 | 40 | Response Elements 41 | ----------------- 42 | 43 | On success, a JSON response will be returned with the following elements: 44 | 45 | id 46 | ^^ 47 | The UUID of the dataset object. 48 | 49 | type 50 | ^^^^ 51 | A JSON object representing the type of the dataset. See :doc:`../Types/index` for 52 | details of the type representation. 53 | 54 | shape 55 | ^^^^^ 56 | A JSON object representing the shape of the dataset. See :doc:`GET_DatasetShape` for 57 | details of the shape representation. 58 | 59 | creationProperties 60 | ^^^^^^^^^^^^^^^^^^ 61 | A JSON object that describes chunk layout, filters, fill value, and other aspects of the dataset. 62 | See: http://hdf5-json.readthedocs.org/en/latest/bnf/dataset.html#grammar-token-dcpl for a complete 63 | description of fields that can be used. 64 | 65 | attributeCount 66 | ^^^^^^^^^^^^^^ 67 | The number of attributes belonging to the dataset. 68 | 69 | created 70 | ^^^^^^^ 71 | A timestamp giving the time the dataset was created in UTC (ISO-8601 format). 72 | 73 | lastModified 74 | ^^^^^^^^^^^^ 75 | A timestamp giving the most recent time the group has been modified (i.e. attributes or 76 | links updated) in UTC (ISO-8601 format). 77 | 78 | hrefs 79 | ^^^^^ 80 | An array of links to related resources. See :doc:`../Hypermedia`. 81 | 82 | Special Errors 83 | -------------- 84 | 85 | This implementation of the operation does not return special errors. For general 86 | information on standard error codes, see :doc:`../CommonErrorResponses`. 87 | 88 | Examples 89 | ======== 90 | 91 | Sample Request 92 | -------------- 93 | 94 | .. code-block:: http 95 | 96 | GET /datasets/c8d83759-a2c6-11e4-8713-3c15c2da029e HTTP/1.1 97 | host: tall.test.hdfgroup.org 98 | Accept-Encoding: gzip, deflate 99 | Accept: */* 100 | User-Agent: python-requests/2.3.0 CPython/2.7.8 Darwin/14.0.0 101 | 102 | Sample Response 103 | --------------- 104 | 105 | .. code-block:: http 106 | 107 | HTTP/1.1 200 OK 108 | Date: Fri, 23 Jan 2015 06:15:33 GMT 109 | Content-Length: 755 110 | Etag: "ecbd7e52654b0a8f4ccbebac06175ce5df5f8c79" 111 | Content-Type: application/json 112 | Server: TornadoServer/3.2.2 113 | 114 | .. code-block:: json 115 | 116 | { 117 | "id": "c8d83759-a2c6-11e4-8713-3c15c2da029e", 118 | "shape": { 119 | "dims": [10], 120 | "class": "H5S_SIMPLE" 121 | }, 122 | "type": { 123 | "base": "H5T_IEEE_F32BE", 124 | "class": "H5T_FLOAT" 125 | }, 126 | "creationProperties": { 127 | "allocTime": "H5D_ALLOC_TIME_LATE", 128 | "fillTime": "H5D_FILL_TIME_IFSET", 129 | "layout": { 130 | "class": "H5D_CONTIGUOUS" 131 | } 132 | }, 133 | "attributeCount": 0, 134 | "created": "2015-01-23T06:12:18Z", 135 | "lastModified": "2015-01-23T06:12:18Z", 136 | "hrefs": [ 137 | {"href": "http://tall.test.hdfgroup.org/datasets/c8d83759-a2c6-11e4-8713-3c15c2da029e", "rel": "self"}, 138 | {"href": "http://tall.test.hdfgroup.org/groups/c8d7842b-a2c6-11e4-b4f1-3c15c2da029e", "rel": "root"}, 139 | {"href": "http://tall.test.hdfgroup.org/datasets/c8d83759-a2c6-11e4-8713-3c15c2da029e/attributes", "rel": "attributes"}, 140 | {"href": "http://tall.test.hdfgroup.org/datasets/c8d83759-a2c6-11e4-8713-3c15c2da029e/value", "rel": "data"}, 141 | {"href": "http://tall.test.hdfgroup.org/", "rel": "home"} 142 | ] 143 | } 144 | 145 | Related Resources 146 | ================= 147 | 148 | * :doc:`DELETE_Dataset` 149 | * :doc:`../AttrOps/GET_Attributes` 150 | * :doc:`GET_DatasetShape` 151 | * :doc:`GET_DatasetType` 152 | * :doc:`GET_Datasets` 153 | * :doc:`GET_Value` 154 | * :doc:`POST_Value` 155 | * :doc:`PUT_Value` 156 | 157 | 158 | -------------------------------------------------------------------------------- /DatasetOps/GET_Datasets.rst: -------------------------------------------------------------------------------- 1 | ********************************************** 2 | GET Datasets 3 | ********************************************** 4 | 5 | Description 6 | =========== 7 | Returns UUIDs for all the datasets in a domain. 8 | 9 | Requests 10 | ======== 11 | 12 | Syntax 13 | ------ 14 | .. code-block:: http 15 | 16 | GET /datasets HTTP/1.1 17 | Host: DOMAIN 18 | Authorization: 19 | 20 | Request Parameters 21 | ------------------ 22 | This implementation of the operation uses the following request parameters (both 23 | optional): 24 | 25 | Limit 26 | ^^^^^ 27 | If provided, a positive integer value specifying the maximum number of UUIDs to return. 28 | 29 | Marker 30 | ^^^^^^ 31 | If provided, a string value indicating that only UUIDs that occur after the 32 | marker value will be returned. 33 | 34 | Request Headers 35 | --------------- 36 | This implementation of the operation uses only the request headers that are common 37 | to most requests. See :doc:`../CommonRequestHeaders` 38 | 39 | Responses 40 | ========= 41 | 42 | Response Headers 43 | ---------------- 44 | 45 | This implementation of the operation uses only response headers that are common to 46 | most responses. See :doc:`../CommonResponseHeaders`. 47 | 48 | Response Elements 49 | ----------------- 50 | 51 | On success, a JSON response will be returned with the following elements: 52 | 53 | datasets 54 | ^^^^^^^^ 55 | An array of UUIDs, one for each dataset in the domain. 56 | 57 | hrefs 58 | ^^^^^ 59 | An array of links to related resources. See :doc:`../Hypermedia`. 60 | 61 | Special Errors 62 | -------------- 63 | 64 | This implementation of the operation does not return special errors. For general 65 | information on standard error codes, see :doc:`../CommonErrorResponses`. 66 | 67 | Examples 68 | ======== 69 | 70 | Sample Request 71 | -------------- 72 | 73 | .. code-block:: http 74 | 75 | GET /datasets HTTP/1.1 76 | host: tall.test.hdfgroup.org 77 | Accept-Encoding: gzip, deflate 78 | Accept: */* 79 | User-Agent: python-requests/2.3.0 CPython/2.7.8 Darwin/14.0.0 80 | 81 | Sample Response 82 | --------------- 83 | 84 | .. code-block:: http 85 | 86 | HTTP/1.1 200 OK 87 | Date: Fri, 23 Jan 2015 06:33:36 GMT 88 | Content-Length: 413 89 | Etag: "977e96c7bc63a6e05d10d56565df2ab8d30e404d" 90 | Content-Type: application/json 91 | Server: TornadoServer/3.2.2 92 | 93 | .. code-block:: json 94 | 95 | 96 | { 97 | "datasets": [ 98 | "c8d7dd14-a2c6-11e4-a68c-3c15c2da029e", 99 | "c8d7f159-a2c6-11e4-99af-3c15c2da029e", 100 | "c8d83759-a2c6-11e4-8713-3c15c2da029e", 101 | "c8d84a8a-a2c6-11e4-b457-3c15c2da029e" 102 | ], 103 | "hrefs": [ 104 | {"href": "http://tall.test.hdfgroup.org/datasets", "rel": "self"}, 105 | {"href": "http://tall.test.hdfgroup.org/groups/c8d7842b-a2c6-11e4-b4f1-3c15c2da029e", "rel": "root"}, 106 | {"href": "http://tall.test.hdfgroup.org/", "rel": "home"} 107 | ] 108 | } 109 | 110 | Sample Request with Marker and Limit 111 | ------------------------------------ 112 | 113 | This example uses the "Marker" request parameter to return only UUIDs after the given 114 | Marker value. 115 | The "Limit" request parameter is used to limit the number of UUIDs in the response to 5. 116 | 117 | .. code-block:: http 118 | 119 | GET /datasets?Marker=817db263-a2cc-11e4-87f2-3c15c2da029e&Limit=5 HTTP/1.1 120 | host: dset1k.test.hdfgroup.org 121 | Accept-Encoding: gzip, deflate 122 | Accept: */* 123 | User-Agent: python-requests/2.3.0 CPython/2.7.8 Darwin/14.0.0 124 | 125 | Sample Response with Marker and Limit 126 | ------------------------------------- 127 | 128 | .. code-block:: http 129 | 130 | HTTP/1.1 200 OK 131 | Date: Fri, 23 Jan 2015 06:53:52 GMT 132 | Content-Length: 459 133 | Etag: "cb708d4839cc1e165fe6bb30718e49589ef140f4" 134 | Content-Type: application/json 135 | Server: TornadoServer/3.2.2 136 | 137 | .. code-block:: json 138 | 139 | { 140 | "datasets": [ 141 | "817dcfb8-a2cc-11e4-9197-3c15c2da029e", 142 | "817de9ee-a2cc-11e4-8378-3c15c2da029e", 143 | "817e028a-a2cc-11e4-8ce3-3c15c2da029e", 144 | "817e1b61-a2cc-11e4-ba39-3c15c2da029e", 145 | "817e341c-a2cc-11e4-a16f-3c15c2da029e" 146 | ], 147 | "hrefs": [ 148 | {"href": "http://dset1k.test.hdfgroup.org/datasets", "rel": "self"}, 149 | {"href": "http://dset1k.test.hdfgroup.org/groups/81760a80-a2cc-11e4-bb55-3c15c2da029e", "rel": "root"}, 150 | {"href": "http://dset1k.test.hdfgroup.org/", "rel": "home"} 151 | ] 152 | } 153 | 154 | Related Resources 155 | ================= 156 | 157 | * :doc:`DELETE_Dataset` 158 | * :doc:`GET_Dataset` 159 | * :doc:`POST_Dataset` 160 | 161 | 162 | -------------------------------------------------------------------------------- /AclOps/GET_ACLs.md: -------------------------------------------------------------------------------- 1 | GET ACLs 2 | ======== 3 | 4 | Description 5 | ----------- 6 | 7 | Returns access information for all users defined in the ACL (Access Control List) for the object with the UUID provided in the URI. 8 | 9 | Requests 10 | -------- 11 | 12 | ### Syntax 13 | 14 | To get the ACL for a domain: 15 | 16 | ``` sourceCode 17 | GET /acls HTTP/1.1 18 | Host: DOMAIN 19 | Authorization: 20 | ``` 21 | 22 | To get the ACL for a group: 23 | 24 | ``` sourceCode 25 | GET /groups//acls HTTP/1.1 26 | Host: DOMAIN 27 | Authorization: 28 | ``` 29 | 30 | To get the ACL for a dataset: 31 | 32 | ``` sourceCode 33 | GET /datasets//acls HTTP/1.1 34 | Host: DOMAIN 35 | Authorization: 36 | ``` 37 | 38 | To get the ACL for a committed datatype: 39 | 40 | ``` sourceCode 41 | GET /datatypes//acls HTTP/1.1 42 | Host: DOMAIN 43 | Authorization: 44 | ``` 45 | 46 | where: 47 | 48 | - <id> is the UUID of the requested dataset/group/committed datatype 49 | 50 | ### Request Parameters 51 | 52 | This implementation of the operation does not use request parameters. 53 | 54 | ### Request Headers 55 | 56 | This implementation of the operation uses only the request headers that are common to most requests. See ../CommonRequestHeaders 57 | 58 | Responses 59 | --------- 60 | 61 | ### Response Headers 62 | 63 | This implementation of the operation uses only response headers that are common to most responses. See ../CommonResponseHeaders. 64 | 65 | ### Response Elements 66 | 67 | On success, a JSON response will be returned with the following elements: 68 | 69 | #### acls 70 | 71 | A JSON list that contains one element for each user specified in the ACL. The elements will be JSON objects that describe each user's access permissions. The subkeys of each element are: 72 | 73 | userName: the userid of the user ('default' for the default access) 74 | 75 | create: A boolean flag that indicates if the user is authorized to create new resources 76 | 77 | delete: A boolean flag that indicates if the user is authorized to delete resources 78 | 79 | read: A boolean flag that indicates if the user is authorized to read (GET) resources 80 | 81 | update: A boolean flag that indicates if the user is authorized to update resources 82 | 83 | readACL: A boolean flag that indicates if the user is authorized to read the object's ACL 84 | 85 | updateACL: A boolean flag that indicates if the user is authorized to update the object's ACL 86 | 87 | #### hrefs 88 | 89 | An array of hypertext links to related resources. See ../Hypermedia. 90 | 91 | ### Special Errors 92 | 93 | This implementation of the operation does not return special errors. For general information on standard error codes, see ../CommonErrorResponses. 94 | 95 | Examples 96 | -------- 97 | 98 | ### Sample Request 99 | 100 | ``` sourceCode 101 | GET /groups/052dcbbd-9d33-11e4-86ce-3c15c2da029e/acls HTTP/1.1 102 | host: tall.test.hdfgroup.org 103 | Accept-Encoding: gzip, deflate 104 | Accept: */* 105 | User-Agent: python-requests/2.3.0 CPython/2.7.8 Darwin/14.0.0 106 | ``` 107 | 108 | ### Sample Response 109 | 110 | ``` sourceCode 111 | HTTP/1.1 200 OK 112 | Date: Fri, 16 Jan 2015 20:06:08 GMT 113 | Content-Length: 660 114 | Etag: "2c410d1c469786f25ed0075571a8e7a3f313cec1" 115 | Content-Type: application/json 116 | Server: TornadoServer/3.2.2 117 | ``` 118 | 119 | ``` sourceCode 120 | { 121 | "acls": [ 122 | { 123 | "create": true, 124 | "delete": true, 125 | "read": true, 126 | "readACL": true, 127 | "update": true, 128 | "updateACL": true, 129 | "userName": "test_user2" 130 | }, 131 | { 132 | "create": false, 133 | "delete": false, 134 | "read": true, 135 | "readACL": false, 136 | "update": false, 137 | "updateACL": false, 138 | "userName": "test_user1" 139 | }, 140 | { 141 | "create": false, 142 | "delete": false, 143 | "read": false, 144 | "readACL": false, 145 | "update": false, 146 | "updateACL": false, 147 | "userName": "default" 148 | } 149 | ], 150 | "hrefs": [ 151 | { 152 | "href": "http://tall_acl.test.hdfgroup.org/groups/eb8f6959-8775-11e5-96b6-3c15c2da029e/acls", 153 | "rel": "self" 154 | }, 155 | { 156 | "href": "http://tall_acl.test.hdfgroup.org/groups/eb8f6959-8775-11e5-96b6-3c15c2da029e", 157 | "rel": "root" 158 | }, 159 | { 160 | "href": "http://tall_acl.test.hdfgroup.org/", 161 | "rel": "home" 162 | }, 163 | { 164 | "href": "http://tall_acl.test.hdfgroup.org/groups/eb8f6959-8775-11e5-96b6-3c15c2da029e", 165 | "rel": "owner" 166 | } 167 | ] 168 | ``` 169 | 170 | Related Resources 171 | ----------------- 172 | 173 | - PUT\_ACL 174 | - GET\_ACL 175 | 176 | -------------------------------------------------------------------------------- /GroupOps/POST_Group.md: -------------------------------------------------------------------------------- 1 | POST Group 2 | ========== 3 | 4 | Description 5 | ----------- 6 | 7 | Creates a new Group. 8 | 9 | *Note:* By default the new Group will not be linked from any other group in the domain. A link element can be included in the request body to have an existing group link to the new group. Alternatively, use the *PUT link* operation to link the new group. 10 | 11 | Requests 12 | -------- 13 | 14 | ### Syntax 15 | 16 | ``` sourceCode 17 | POST /groups HTTP/1.1 18 | X-Hdf-domain: DOMAIN 19 | Authorization: 20 | ``` 21 | 22 | ``` sourceCode 23 | POST /groups?domain=DOMAIN HTTP/1.1 24 | Authorization: 25 | ``` 26 | 27 | ### Request Parameters 28 | 29 | This implementation of the operation does not use request parameters. 30 | 31 | ### Request Headers 32 | 33 | This implementation of the operation uses only the request headers that are common to most requests. See ../CommonRequestHeaders 34 | 35 | ### Request Elements 36 | 37 | Optionally the request body can be a JSON object that has a link key with sub-keys: 38 | 39 | #### id 40 | 41 | The UUID of the group that the new group should be linked to. If the UUID is not valid, the request will fail and a new group will not be created. 42 | 43 | #### name 44 | 45 | The name of the new link. 46 | 47 | Responses 48 | --------- 49 | 50 | ### Response Headers 51 | 52 | This implementation of the operation uses only response headers that are common to most responses. See ../CommonResponseHeaders. 53 | 54 | ### Response Elements 55 | 56 | On success, a JSON response will be returned with the following elements: 57 | 58 | #### id 59 | 60 | The UUID of the newly created group. 61 | 62 | #### root 63 | 64 | The root group of the domain which the group was created in. 65 | 66 | #### attributeCount 67 | 68 | The number of attributes belonging to the group. 69 | 70 | #### linkCount 71 | 72 | The number of links belonging to the group. 73 | 74 | #### created 75 | 76 | A timestamp giving the time the group was created in UTC (ISO-8601 format). 77 | 78 | #### lastModified 79 | 80 | A timestamp giving the most recent time the group has been modified (i.e. attributes or links updated) in UTC (ISO-8601 format). 81 | 82 | ### Special Errors 83 | 84 | This implementation of the operation does not return special errors. For general information on standard error codes, see ../CommonErrorResponses. 85 | 86 | Examples 87 | -------- 88 | 89 | ### Sample Request 90 | 91 | Create a new, un-linked Group. 92 | 93 | ``` sourceCode 94 | POST /groups HTTP/1.1 95 | Host: hsdshdflab.hdfgroup.org 96 | X-Hdf-domain: /shared/tall.h5 97 | Content-Length: 0 98 | Accept: */* 99 | Accept-Encoding: gzip, deflate 100 | ``` 101 | 102 | ### Sample cURL command 103 | 104 | ``` sourceCode 105 | $ curl -X POST -u username:password --header "X-Hdf-domain: /shared/tall.h5" hsdshdflab.hdfgroup.org/groups 106 | ``` 107 | 108 | ### Sample Response 109 | 110 | ``` sourceCode 111 | HTTP/1.1 201 Created 112 | Content-Length: 202 113 | Server: nginx/1.15.0 114 | Date: Thu, 12 Jul 2018 16:49:10 GMT 115 | Content-Type: application/json 116 | ``` 117 | 118 | ``` sourceCode 119 | { 120 | "id": "g-7fbbf52a-85f3-11e8-9cc2-0242ac120008", 121 | "root": "g-b116b6f0-85e9-11e8-9cc2-0242ac120008", 122 | "created": 1531414150.1522243, 123 | "lastModified": 1531414150.1522243, 124 | "linkCount": 0, 125 | "attributeCount": 0 126 | } 127 | ``` 128 | 129 | ### Sample Request with Link 130 | 131 | Create a new Group, link to root (which has uuid of "g-b116b6f0-...") as "linked\_group". 132 | 133 | ``` sourceCode 134 | POST /groups HTTP/1.1 135 | Host: hsdshdflab.hdfgroup.org 136 | X-Hdf-domain: /shared/tall.h5 137 | Content-Length: 82 138 | Accept: */* 139 | Accept-Encoding: gzip, deflate 140 | ``` 141 | 142 | ``` sourceCode 143 | { 144 | "link": { 145 | "id": "g-b116b6f0-85e9-11e8-9cc2-0242ac120008", 146 | "name": "linked_group" 147 | } 148 | } 149 | ``` 150 | 151 | ### Sample cURL command 152 | 153 | ``` sourceCode 154 | $ curl -X POST -u username:password --header "X-Hdf-domain: /shared/tall.h5" 155 | -d "{\"link\": {\"id\": \"g-b116b6f0-85e9-11e8-9cc2-0242ac120008\", \"name\": \"linked_group\"}}" hsdshdflab.hdfgroup.org/groups 156 | ``` 157 | 158 | ### Sample Response with Link 159 | 160 | ``` sourceCode 161 | HTTP/1.1 201 Created 162 | Content-Length: 200 163 | Server: nginx/1.15.0 164 | Date: Thu, 12 Jul 2018 16:57:57 GMT 165 | Content-Type: application/json 166 | ``` 167 | 168 | ``` sourceCode 169 | { 170 | "id": "g-b9bd362a-85f4-11e8-a549-0242ac12000b", 171 | "root": "g-b116b6f0-85e9-11e8-9cc2-0242ac120008", 172 | "linkCount": 0, 173 | "attributeCount": 0, 174 | "lastModified": 1531414676.963812, 175 | "created": 1531414676.963812 176 | } 177 | ``` 178 | 179 | Related Resources 180 | ----------------- 181 | 182 | - DELETE\_Group 183 | - GET\_Links 184 | - PUT\_Link 185 | - GET\_Group 186 | - GET\_Groups 187 | 188 | -------------------------------------------------------------------------------- /AclOps/GET_ACL.rst: -------------------------------------------------------------------------------- 1 | ********************************************** 2 | GET ACL 3 | ********************************************** 4 | 5 | Description 6 | =========== 7 | Returns access information for the given user for the object with the UUID provided in the URI. 8 | 9 | Requests 10 | ======== 11 | 12 | Syntax 13 | ------ 14 | 15 | To get a user's default access for a domain: 16 | 17 | .. code-block:: http 18 | 19 | GET /acls/ HTTP/1.1 20 | Host: DOMAIN 21 | Authorization: 22 | 23 | To get a user's access information for a group: 24 | 25 | .. code-block:: http 26 | 27 | GET /groups//acls/ HTTP/1.1 28 | Host: DOMAIN 29 | Authorization: 30 | 31 | To get a user's access information for a dataset: 32 | 33 | .. code-block:: http 34 | 35 | GET /datasets//acls/ HTTP/1.1 36 | Host: DOMAIN 37 | Authorization: 38 | 39 | 40 | To get a user's access information for a committed datatype: 41 | 42 | .. code-block:: http 43 | 44 | GET /datatypes//acls/ HTTP/1.1 45 | Host: DOMAIN 46 | Authorization: 47 | 48 | where: 49 | 50 | * is the UUID of the requested dataset/group/committed datatype 51 | * is the userid for the requested user. Use the special userid "default" to get the default access permisions for the object 52 | 53 | Request Parameters 54 | ------------------ 55 | This implementation of the operation does not use request parameters. 56 | 57 | Request Headers 58 | --------------- 59 | This implementation of the operation uses only the request headers that are common 60 | to most requests. See :doc:`../CommonRequestHeaders` 61 | 62 | Responses 63 | ========= 64 | 65 | Response Headers 66 | ---------------- 67 | 68 | This implementation of the operation uses only response headers that are common to 69 | most responses. See :doc:`../CommonResponseHeaders`. 70 | 71 | Response Elements 72 | ----------------- 73 | 74 | On success, a JSON response will be returned with the following elements: 75 | 76 | 77 | acl 78 | ^^^ 79 | A JSON object that describes a user's access permissions. Subkeys of acl are: 80 | 81 | userName: the userid of the requested user 82 | 83 | create: A boolean flag that indicates if the user is authorized to create new resources 84 | 85 | delete: A boolean flag that indicates if the user is authorized to delete resources 86 | 87 | read: A boolean flag that indicates if the user is authorized to read (GET) resources 88 | 89 | update: A boolean flag that indicates if the user is authorized to update resources 90 | 91 | readACL: A boolean flag that indicates if the user is authorized to read the object's ACL 92 | 93 | updateACL: A boolean flag that indicates if the user is authorized to update the object's ACL 94 | 95 | 96 | hrefs 97 | ^^^^^ 98 | An array of hypertext links to related resources. See :doc:`../Hypermedia`. 99 | 100 | Special Errors 101 | -------------- 102 | 103 | This implementation of the operation does not return special errors. For general 104 | information on standard error codes, see :doc:`../CommonErrorResponses`. 105 | 106 | Examples 107 | ======== 108 | 109 | Sample Request 110 | -------------- 111 | 112 | .. code-block:: http 113 | 114 | GET /groups/052dcbbd-9d33-11e4-86ce-3c15c2da029e/acls/test_user1 HTTP/1.1 115 | host: tall.test.hdfgroup.org 116 | Accept-Encoding: gzip, deflate 117 | Accept: */* 118 | User-Agent: python-requests/2.3.0 CPython/2.7.8 Darwin/14.0.0 119 | 120 | Sample Response 121 | --------------- 122 | 123 | .. code-block:: http 124 | 125 | HTTP/1.1 200 OK 126 | Date: Fri, 16 Jan 2015 20:06:08 GMT 127 | Content-Length: 660 128 | Etag: "2c410d1c469786f25ed0075571a8e7a3f313cec1" 129 | Content-Type: application/json 130 | Server: TornadoServer/3.2.2 131 | 132 | .. code-block:: json 133 | 134 | { 135 | "acl": { 136 | "create": false, 137 | "delete": false, 138 | "read": true, 139 | "readACL": false, 140 | "update": false, 141 | "updateACL": false, 142 | "userName": "test_user1" 143 | }, 144 | "hrefs": [ 145 | { 146 | "href": "http://tall_acl.test.hdfgroup.org/groups/eb8f6959-8775-11e5-96b6-3c15c2da029e/acls/test_user1", 147 | "rel": "self" 148 | }, 149 | { 150 | "href": "http://tall_acl.test.hdfgroup.org/groups/eb8f6959-8775-11e5-96b6-3c15c2da029e", 151 | "rel": "root" 152 | }, 153 | { 154 | "href": "http://tall_acl.test.hdfgroup.org/", 155 | "rel": "home" 156 | }, 157 | { 158 | "href": "http://tall_acl.test.hdfgroup.org/groups/eb8f6959-8775-11e5-96b6-3c15c2da029e", 159 | "rel": "owner" 160 | } 161 | ] 162 | 163 | Related Resources 164 | ================= 165 | 166 | * :doc:`PUT_ACL` 167 | * :doc:`GET_ACLs` 168 | 169 | 170 | 171 | -------------------------------------------------------------------------------- /AclOps/index.md: -------------------------------------------------------------------------------- 1 | Access Control List 2 | =================== 3 | 4 | An Access Control List (ACL) is a key-value store that can be used to manage what operations can be performed by which user on group, dataset, or committed type objects. Operations on other objects (e.g. links, dataspace, or attributes) use the ACL of the object they belong to. 5 | 6 | Each ACL consists of 1 or more items in the form: 7 | 8 | (username, read, create, update, delete, readACL, updateACL) 9 | 10 | where username is a string, and read, create, update, delete, readACL and updateACL are booleans. These flags have the following semantics when the given username is provided in the http Authorization header: 11 | 12 | - read: The given user is authorized for read access to the resource (generally all GET requests) 13 | - create: The given user is authorized to create new resources (generally POST or PUT requests) 14 | - update: The given user is authorized to modified a resource (e.g. ../DatasetOps/PUT\_Value) 15 | - delete: The given user is authorized to delete a resource (e.g. Delete a Group) 16 | - readACL: The given user is authorized to read the ACLs of a resource 17 | - updateACL: The given user is authorized to modify the ACLs of a resource 18 | 19 | A special username 'default' is used to denote the access permission for all other users who are not listed in the ACL (including un-authenticated requests that don't provide a username). 20 | 21 | Example 22 | ------- 23 | 24 | Suppose a given dataset has the following ACL: 25 | 26 | | username | read | create | update | delete | readACL | writeACL | 27 | |----------|------|--------|--------|--------|---------|----------| 28 | | default | true | false | false | false | false | false | 29 | | joe | true | false | true | false | false | false | 30 | | ann | true | true | true | true | true | true | 31 | 32 | This ACL would enable anyone to read (perform GET requests). User 'joe' would be able to read and update (modify values in the dataset). While user 'ann' would have full control to do any operation on the dataset (including modifying permissions for herself or other users). 33 | 34 | The following unauthenticated (no HTTP Authorization header) requests on the dataset would be granted or denied as follows: 35 | 36 | - GET /datasets/<id> - granted (returns HTTP Status 200 - OK) 37 | - POST /datasets/<id>/value - granted (returns HTTP Status 200 - OK) 38 | - PUT /datasets/<id>/shape) - denied (returns HTTP Status 401 - Unauthorized) 39 | - PUT /datasets/<id>/attributes/<name> - denied (returns HTTP Status 401 - Unauthorized) 40 | - DELETE /datasets/<id> - denied (returns HTTP Status 401 - Unauthorized) 41 | 42 | Next the same set of requests are sent with 'joe' as the user in the HTTP Authorization header: 43 | 44 | - GET /datasets/<id> - granted (returns HTTP Status 200 - OK) 45 | - POST /datasets/<id>/value - granted (returns HTTP Status 200 - OK) 46 | - PUT /datasets/<id>/shape) - grant (returns HTTP Status 200 - OK) 47 | - PUT /datasets/<id>/attributes/<name> - denied (returns HTTP Status 403 - Forbidden) 48 | - DELETE /datasets/<id> - denied (returns HTTP Status 403 - Forbidden) 49 | 50 | Finally the same set of requests are sent with 'ann' as the user: 51 | 52 | - GET /datasets/<id> - granted (returns HTTP Status 200 - OK) 53 | - POST /datasets/<id>/value - granted (returns HTTP Status 200 - OK) 54 | - PUT /datasets/<id>/shape) - grant (returns HTTP Status 200 - OK) 55 | - PUT /datasets/<id>/attributes/<name> - denied (returns HTTP Status 201 - Created) 56 | - DELETE /datasets/<id> - denied (returns HTTP Status 200 - OK) 57 | 58 | Note: HTTP Status 401 basically says: "you can't have access until you tell me who you are", while HTTP Status 403 says: "I know who you are, but you don't have permissions to access this resource." 59 | 60 | Root ACL Inheritance 61 | -------------------- 62 | 63 | In many cases it will be desired to have a default ACL that applies to each resource in the domain. This can be accomplished by defining an ACL for the root group. This will control the access rights for any resource unless an ACL is present in that resource for the requesting user. 64 | 65 | The default ACL can be read or updated by forming a request with a uri that includes the root group id, i.e.: "/groups/<root\_id>/acls", or by using the uri path for the domain, i.e. "/acls". 66 | 67 | For a given user then, the permissions for a resource are found in the following way: 68 | 69 | 1. If the user is present in the resources ACL, those permissions are used 70 | 2. If no user is present in the resources ACL, but is present in the root group, those permissions are used 71 | 3. Otherwise, if a 'default' user is present in the resource ACL, those permissions are used 72 | 4. If a 'default' user is not present in the resource ACL, but is present in the root ACL, those permissions are used 73 | 5. If no 'default' user is present in the root ACL, the permissions defined in the 'default\_acl' config is used 74 | 75 | List of Operations 76 | ------------------ 77 | -------------------------------------------------------------------------------- /AttrOps/GET_Attribute.md: -------------------------------------------------------------------------------- 1 | GET Attribute 2 | ============= 3 | 4 | Description 5 | ----------- 6 | 7 | Gets the specified attribute of a dataset, group, or committed datatype. 8 | 9 | Requests 10 | -------- 11 | 12 | ### Syntax 13 | 14 | To get an attribute of a group: 15 | 16 | ``` sourceCode 17 | GET /groups//attributes/ HTTP/1.1 18 | X-Hdf-domain: DOMAIN 19 | Authorization: 20 | ``` 21 | 22 | ``` sourceCode 23 | GET /groups//attributes/?domain=DOMAIN HTTP/1.1 24 | Authorization: 25 | ``` 26 | 27 | To get an attribute of a dataset: 28 | 29 | ``` sourceCode 30 | GET /datasets//attributes/ HTTP/1.1 31 | X-Hdf-domain: DOMAIN 32 | Authorization: 33 | ``` 34 | 35 | ``` sourceCode 36 | GET /datasets//attributes/?domain=DOMAIN HTTP/1.1 37 | Authorization: 38 | ``` 39 | 40 | To get an attribute of a datatype: 41 | 42 | ``` sourceCode 43 | GET /datatypes//attributes/ HTTP/1.1 44 | X-Hdf-domain: DOMAIN 45 | Authorization: 46 | ``` 47 | 48 | ``` sourceCode 49 | GET /datatypes//attributes/?domain=DOMAIN HTTP/1.1 50 | Authorization: 51 | ``` 52 | 53 | where: 54 | 55 | - *<id>* is the UUID of the dataset/group/committed datatype 56 | - *<name>* is the url-encoded name of the requested attribute 57 | 58 | ### Request Parameters 59 | 60 | This implementation of the operation does not use request parameters. 61 | 62 | ### Request Headers 63 | 64 | This implementation of the operation uses only the request headers that are common to most requests. See ../CommonRequestHeaders 65 | 66 | Responses 67 | --------- 68 | 69 | ### Response Headers 70 | 71 | This implementation of the operation uses only response headers that are common to most responses. See ../CommonResponseHeaders. 72 | 73 | ### Response Elements 74 | 75 | On success, a JSON response will be returned with the following elements: 76 | 77 | #### type 78 | 79 | A JSON object representing the type of the attribute. See ../Types/index for details of the type representation. 80 | 81 | #### shape 82 | 83 | A JSON object that represents the dataspace of the attribute. Subkeys of shape are: 84 | 85 | class: A string with one of the following values: 86 | 87 | > - H5S\_NULL: A null dataspace, which has no elements 88 | > - H5S\_SCALAR: A dataspace with a single element (although possibly of a complex datatype) 89 | > - H5S\_SIMPLE: A dataspace that consists of a regular array of elements 90 | 91 | dims: An integer array whose length is equal to the number of dimensions (rank) of the dataspace. The value of each element gives the current size of each dimension. Dims is not returned for H5S\_NULL or H5S\_SCALAR dataspaces. 92 | 93 | #### value 94 | 95 | A JSON array (or string or number for scalar datasets) giving the values of the requested attribute. 96 | 97 | #### hrefs 98 | 99 | An array of links to related resources. See ../Hypermedia. 100 | 101 | ### Special Errors 102 | 103 | This implementation of the operation does not return special errors. For general information on standard error codes, see ../CommonErrorResponses. 104 | 105 | Examples 106 | -------- 107 | 108 | ### Sample Request 109 | 110 | Get an attribute named "attr1" from a group with UUID: "g-be5996fa-...". 111 | 112 | ``` sourceCode 113 | GET /groups/g-be5996fa-83c5-11e8-a8e6-0242ac120016/attributes/attr1 HTTP/1.1 114 | Host: hsdshdflab.hdfgroup.org 115 | X-Hdf-domain: /shared/tall.h5 116 | Accept-Encoding: gzip, deflate 117 | Accept: */* 118 | ``` 119 | 120 | ### Sample cURL command 121 | 122 | ``` sourceCode 123 | $ curl -X GET --header "X-Hdf-domain: /shared/tall.h5" hsdshdflab.hdfgroup.org/groups/g-be5996fa-83c5-11e8-a8e6-0242ac120016/attributes/attr1 124 | ``` 125 | 126 | ### Sample Response 127 | 128 | ``` sourceCode 129 | HTTP/1.1 200 OK 130 | Date: Sun, 15 Jul 2018 16:17:44 GMT 131 | Content-Length: 522 132 | Etag: "55b2e2ce2d3a2449a49cfd76c4dae635ec43a150" 133 | Content-Type: application/json 134 | Server: nginx/1.15.0 135 | ``` 136 | 137 | ``` sourceCode 138 | { 139 | "name": "attr1", 140 | "type": { 141 | "base": "H5T_STD_I8LE", 142 | "class": "H5T_INTEGER" 143 | }, 144 | "shape": { 145 | "class": "H5S_SIMPLE", 146 | "dims": [10] 147 | }, 148 | "created": 1531174596.117736, 149 | "lastModified": 1531174596.117736, 150 | "value": [97, 98, 99, 100, 101, 102, 103, 104, 105, 0], 151 | "hrefs": [ 152 | {"href": "hsdshdflab.hdfgroup.org/groups/g-be5996fa-83c5-11e8-a8e6-0242ac120016/attributes/attr1", "rel": "self"}, 153 | {"href": "hsdshdflab.hdfgroup.org/", "rel": "home"}, 154 | {"href": "hsdshdflab.hdfgroup.org/groups/g-be5996fa-83c5-11e8-a8e6-0242ac120016", "rel": "owner"} 155 | ] 156 | } 157 | ``` 158 | 159 | Related Resources 160 | ----------------- 161 | 162 | - DELETE\_Attribute 163 | - GET\_Attributes 164 | - ../DatasetOps/GET\_Dataset 165 | - ../DatatypeOps/GET\_Datatype 166 | - ../GroupOps/GET\_Group 167 | - PUT\_Attribute 168 | 169 | -------------------------------------------------------------------------------- /Resources.md: -------------------------------------------------------------------------------- 1 | Resource List 2 | ============= 3 | 4 | List of Resources 5 | ----------------- 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 32 | 35 | 38 | 41 | 42 | 43 | 44 | 45 | 48 | 51 | 54 | 57 | 58 | 59 | 60 | 61 | 64 | 67 | 70 | 73 | 74 | 75 | 76 | 77 | 80 | 83 | 86 | 89 | 90 | 91 | 92 | 93 | 96 | 99 | 102 | 105 | 106 | 107 | 108 | 109 | 112 | 115 | 118 | 121 | 122 | 123 | 124 | 125 | 128 | 131 | 134 | 137 | 138 | 139 | 140 | 141 | 144 | 147 | 150 | 153 | 154 | 155 | 156 | 157 | 160 | 163 | 166 | 169 | 170 | 171 | 172 | 173 | 176 | 179 | 182 | 185 | 186 | 187 | 188 | 189 | 192 | 195 | 198 | 201 | 202 | 203 | 204 | 205 | 208 | 211 | 214 | 217 | 218 | 219 | 220 | 221 | 224 | 227 | 230 | 233 | 234 | 235 | 236 | 237 | 240 | 243 | 246 | 249 | 250 | 251 | 252 |
ResourceGETPUTPOSTDELETEDescription
Domain
30 |

Y

31 |
33 |

Y

34 |
36 |

N

37 |
39 |

Y

40 |
A related collection of HDF objects
Group
46 |

Y

47 |
49 |

N

50 |
52 |

N

53 |
55 |

Y

56 |
Represents an HDF Group
Links
62 |

Y

63 |
65 |

N

66 |
68 |

N

69 |
71 |

N

72 |
Collection of links within a group
Link
78 |

Y

79 |
81 |

Y

82 |
84 |

N

85 |
87 |

Y

88 |
Represents an HDF link
Dataset
94 |

Y

95 |
97 |

N

98 |
100 |

N

101 |
103 |

Y

104 |
Represents an HDF Dataset
Attributes
110 |

Y

111 |
113 |

N

114 |
116 |

N

117 |
119 |

N

120 |
Collection of Attributes
Attribute
126 |

Y

127 |
129 |

Y

130 |
132 |

N

133 |
135 |

Y

136 |
Represents an HDF Attribute
Dataspace
142 |

Y

143 |
145 |

Y

146 |
148 |

N

149 |
151 |

N

152 |
Shape of a dataset
Type
158 |

Y

159 |
161 |

N

162 |
164 |

N

165 |
167 |

N

168 |
Type of a dataset
Value
174 |

Y

175 |
177 |

Y

178 |
180 |

Y

181 |
183 |

N

184 |
Data values of a datset
Datatype
190 |

Y

191 |
193 |

N

194 |
196 |

N

197 |
199 |

Y

200 |
Committed datatype
Groups
206 |

Y

207 |
209 |

N

210 |
212 |

Y

213 |
215 |

N

216 |
Collection of groups within a domain
Datasets
222 |

Y

223 |
225 |

N

226 |
228 |

Y

229 |
231 |

N

232 |
Collection of datasets within a domain
Datatypes
238 |

Y

239 |
241 |

N

242 |
244 |

Y

245 |
247 |

N

248 |
Collection of datatypes within a domain
253 | 254 | 255 | -------------------------------------------------------------------------------- /DatasetOps/GET_DatasetShape.md: -------------------------------------------------------------------------------- 1 | GET Shape 2 | ========= 3 | 4 | Description 5 | ----------- 6 | 7 | Gets the shape of a dataset. 8 | 9 | Requests 10 | -------- 11 | 12 | ### Syntax 13 | 14 | ``` sourceCode 15 | GET /datasets//shape HTTP/1.1 16 | Host: DOMAIN 17 | Authorization: 18 | ``` 19 | 20 | *<id>* is the UUID of the dataset that shape is requested for. 21 | 22 | ### Request Parameters 23 | 24 | This implementation of the operation does not use request parameters. 25 | 26 | ### Request Headers 27 | 28 | This implementation of the operation uses only the request headers that are common to most requests. See ../CommonRequestHeaders 29 | 30 | Responses 31 | --------- 32 | 33 | ### Response Headers 34 | 35 | This implementation of the operation uses only response headers that are common to most responses. See ../CommonResponseHeaders. 36 | 37 | ### Response Elements 38 | 39 | On success, a JSON response will be returned with the following elements: 40 | 41 | #### shape 42 | 43 | A JSON object with the following keys: 44 | 45 | class: A string with one of the following values: 46 | 47 | > - H5S\_NULL: A null dataspace, which has no elements 48 | > - H5S\_SCALAR: A dataspace with a single element (although possibly of a complex datatype) 49 | > - H5S\_SIMPLE: A dataspace that consists of a regular array of elements 50 | 51 | dims: An integer array whose length is equal to the number of dimensions (rank) of the dataspace. The value of each element gives the current size of each dimension. Dims is not returned for H5S\_NULL or H5S\_SCALAR dataspaces. 52 | 53 | maxdims: An integer array whose length is equal to the number of dimensions of the dataspace. The value of each element gives the maximum size of each dimension. A value of 0 indicates that the dimension has *unlimited* extent. maxdims is not returned for H5S\_SIMPLE dataspaces which are not extensible or for H5S\_NULL or H5S\_SCALAR dataspaces. 54 | 55 | fillvalue: A value, of a type compatible with the dataset's type, which gives the *fill* value for the dataset (the value which elements will be initialized to when a dataspace is extended). fillvalue is only returned for extensible dataspaces. 56 | 57 | #### created 58 | 59 | A timestamp giving the time the datashape (same as the dataset) was created in UTC (ISO-8601 format). 60 | 61 | #### lastModified 62 | 63 | A timestamp giving the most recent time the dataspace has been modified (i.e. a dimension has been extended) in UTC (ISO-8601 format). 64 | 65 | #### hrefs 66 | 67 | An array of links to related resources. See ../Hypermedia. 68 | 69 | ### Special Errors 70 | 71 | This implementation of the operation does not return special errors. For general information on standard error codes, see ../CommonErrorResponses. 72 | 73 | Examples 74 | -------- 75 | 76 | ### Sample Request 77 | 78 | ``` sourceCode 79 | GET /datasets/3b57b6d4-a6a8-11e4-96b5-3c15c2da029e/shape HTTP/1.1 80 | host: tall.test.hdfgroup.org 81 | Accept-Encoding: gzip, deflate 82 | Accept: */* 83 | User-Agent: python-requests/2.3.0 CPython/2.7.8 Darwin/14.0.0 84 | ``` 85 | 86 | ### Sample Response 87 | 88 | ``` sourceCode 89 | HTTP/1.1 200 OK 90 | Date: Wed, 28 Jan 2015 04:43:41 GMT 91 | Content-Length: 445 92 | Etag: "76ed777f151c70d0560d1414bffe1515a3df86b0" 93 | Content-Type: application/json 94 | Server: TornadoServer/3.2.2 95 | ``` 96 | 97 | ``` sourceCode 98 | { 99 | "shape": { 100 | "class": "H5S_SIMPLE" 101 | "dims": [10], 102 | }, 103 | "created": "2015-01-28T04:40:23Z", 104 | "lastModified": "2015-01-28T04:40:23Z", 105 | "hrefs": [ 106 | {"href": "http://tall.test.hdfgroup.org/datasets/3b57b6d4-a6a8-11e4-96b5-3c15c2da029e", "rel": "self"}, 107 | {"href": "http://tall.test.hdfgroup.org/datasets/3b57b6d4-a6a8-11e4-96b5-3c15c2da029e", "rel": "owner"}, 108 | {"href": "http://tall.test.hdfgroup.org/groups/3b56ee54-a6a8-11e4-b2ae-3c15c2da029e", "rel": "root"} 109 | ], 110 | } 111 | ``` 112 | 113 | ### Sample Request - Resizable 114 | 115 | ``` sourceCode 116 | GET /datasets/a64010e8-a6aa-11e4-98c8-3c15c2da029e/shape HTTP/1.1 117 | host: resizable.test.hdfgroup.org 118 | Accept-Encoding: gzip, deflate 119 | Accept: */* 120 | User-Agent: python-requests/2.3.0 CPython/2.7.8 Darwin/14.0.0 121 | ``` 122 | 123 | ### Sample Response - Resizable 124 | 125 | ``` sourceCode 126 | HTTP/1.1 200 OK 127 | Date: Wed, 28 Jan 2015 05:00:59 GMT 128 | Content-Length: 500 129 | Etag: "1082800980d6809a8008b22e225f1adde8afc73f" 130 | Content-Type: application/json 131 | Server: TornadoServer/3.2.2 132 | ``` 133 | 134 | ``` sourceCode 135 | { 136 | "shape": { 137 | "class": "H5S_SIMPLE", 138 | "dims": [10, 10], 139 | "maxdims": [10, 0], 140 | }, 141 | "created": "2015-01-28T04:40:23Z", 142 | "lastModified": "2015-01-28T04:40:23Z", 143 | "hrefs": [ 144 | {"href": "http://resizable.test.hdfgroup.org/datasets/a64010e8-a6aa-11e4-98c8-3c15c2da029e", "rel": "self"}, 145 | {"href": "http://resizable.test.hdfgroup.org/datasets/a64010e8-a6aa-11e4-98c8-3c15c2da029e", "rel": "owner"}, 146 | {"href": "http://resizable.test.hdfgroup.org/groups/a63f5dcf-a6aa-11e4-ab68-3c15c2da029e", "rel": "root"} 147 | ] 148 | } 149 | ``` 150 | 151 | Related Resources 152 | ----------------- 153 | 154 | - GET\_Dataset 155 | - GET\_DatasetType 156 | - PUT\_DatasetShape 157 | 158 | -------------------------------------------------------------------------------- /DatatypeOps/GET_Datatypes.md: -------------------------------------------------------------------------------- 1 | GET Datatypes 2 | ============= 3 | 4 | Description 5 | ----------- 6 | 7 | Gets all the committed datatypes in a domain. 8 | 9 | Requests 10 | -------- 11 | 12 | ### Syntax 13 | 14 | ``` sourceCode 15 | GET /datatypes HTTP/1.1 16 | X-Hdf-domain: DOMAIN 17 | Authorization: 18 | ``` 19 | 20 | ``` sourceCode 21 | GET /datatypes?domain=DOMAIN HTTP/1.1 22 | Authorization: 23 | ``` 24 | 25 | ### Request Parameters 26 | 27 | This implementation of the operation uses the following request parameters (both optional): 28 | 29 | #### Limit 30 | 31 | If provided, a positive integer value specifying the maximum number of UUIDs to return. 32 | 33 | #### Marker 34 | 35 | If provided, a string value indicating that only UUIDs that occur after the marker value will be returned. 36 | 37 | ### Request Headers 38 | 39 | This implementation of the operation uses only the request headers that are common to most requests. See ../CommonRequestHeaders 40 | 41 | Responses 42 | --------- 43 | 44 | ### Response Headers 45 | 46 | This implementation of the operation uses only response headers that are common to most responses. See ../CommonResponseHeaders. 47 | 48 | ### Response Elements 49 | 50 | On success, a JSON response will be returned with the following elements: 51 | 52 | #### hrefs 53 | 54 | An array of links to related resources. See ../Hypermedia. 55 | 56 | ### Special Errors 57 | 58 | This implementation of the operation does not return special errors. For general information on standard error codes, see ../CommonErrorResponses. 59 | 60 | Examples 61 | -------- 62 | 63 | ### Sample Request 64 | 65 | ``` sourceCode 66 | GET /datatypes HTTP/1.1 67 | Host: hsdshdflab.hdfgroup.org 68 | X-Hdf-domain: /shared/tall.h5 69 | Accept-Encoding: gzip, deflate 70 | Accept: */* 71 | ``` 72 | 73 | ### Sample cURL command 74 | 75 | ``` sourceCode 76 | $ curl -X GET --header "X-Hdf-domain: /shared/tall.h5" hsdshdflab.hdfgroup.org/datatypes 77 | ``` 78 | 79 | ### Sample Response 80 | 81 | ``` sourceCode 82 | HTTP/1.1 200 OK 83 | Date: Fri, 13 Jul 2018 18:23:58 GMT 84 | Content-Length: 746 85 | Etag: "e01f56869a9a919b1496c463f3569a2a7c319f11" 86 | Content-Type: application/json 87 | Server: nginx/1.15.0 88 | ``` 89 | 90 | ``` sourceCode 91 | { 92 | "datatypes": [ 93 | "t-3e37ab7e-86b3-11e8-bce3-0242ac12000c", 94 | "t-af48f618-86c9-11e8-9cb8-0242ac120008", 95 | "t-b0510adc-86c9-11e8-9361-0242ac120007", 96 | "t-b0e855b8-86c9-11e8-ac22-0242ac12000d", 97 | "t-b17d24fe-86c9-11e8-b364-0242ac12000a", 98 | "t-b21dd3ea-86c9-11e8-9cb8-0242ac120008", 99 | "t-b2b2a380-86c9-11e8-9361-0242ac120007", 100 | "t-b34f3542-86c9-11e8-ac22-0242ac12000d", 101 | "t-b4659570-86c9-11e8-b364-0242ac12000a", 102 | "t-b4f32ffc-86c9-11e8-9cb8-0242ac120008", 103 | "t-b58f2b50-86c9-11e8-9361-0242ac120007", 104 | "t-b66113c2-86c9-11e8-ac22-0242ac12000d", 105 | "t-b6f8e454-86c9-11e8-b364-0242ac12000a" 106 | ], 107 | "hrefs": [ 108 | {"href": "hsdshdflab.hdfgroup.org/datatypes", "rel": "self"}, 109 | {"href": "hsdshdflab.hdfgroup.org/groups/g-b116b6f0-85e9-11e8-9cc2-0242ac120008", "rel": "root"}, 110 | {"href": "hsdshdflab.hdfgroup.org/", "rel": "home"} 111 | ] 112 | } 113 | ``` 114 | 115 | ### Sample Request with Marker and Limit 116 | 117 | This example uses the "Marker" request parameter to return only UUIDs after the given Marker value. Also, the "Limit" request parameter is used to limit the number of UUIDs in the response to 5. 118 | 119 | ``` sourceCode 120 | GET /datatypes?Marker=t-b17d24fe-86c9-11e8-b364-0242ac12000a&Limit=5 HTTP/1.1 121 | Host: hsdshdflab.hdfgroup.org 122 | X-Hdf-domain: /shared/tall.h5 123 | Accept-Encoding: gzip, deflate 124 | Accept: */* 125 | ``` 126 | 127 | ### Sample cURL command 128 | 129 | *URL enclosed in quotes to prevent shell from seeing ampersand* 130 | 131 | ``` sourceCode 132 | $ curl -X GET --header "X-Hdf-domain: /shared/tall.h5" "hsdshdflab.hdfgroup.org/datatypes?Marker=t-b17d24fe-86c9-11e8-b364-0242ac12000a&Limit=5" 133 | ``` 134 | 135 | ### Sample Response with Marker and Limit 136 | 137 | > ``` sourceCode 138 | > HTTP/1.1 200 OK 139 | > Date: Fri, 13 Jul 2018 18:30:29 GMT 140 | > Content-Length: 410 141 | > Etag: "a2e2d5a3ae63cd504d02b51d99f27b30d17b75b5" 142 | > Content-Type: application/json 143 | > Server: nginx/1.15.0 144 | > ``` 145 | > 146 | > ``` sourceCode 147 | > { 148 | > "datatypes": [ 149 | > "t-b21dd3ea-86c9-11e8-9cb8-0242ac120008", 150 | > "t-b2b2a380-86c9-11e8-9361-0242ac120007", 151 | > "t-b34f3542-86c9-11e8-ac22-0242ac12000d", 152 | > "t-b4659570-86c9-11e8-b364-0242ac12000a", 153 | > "t-b4f32ffc-86c9-11e8-9cb8-0242ac120008" 154 | > ], 155 | > "hrefs": [ 156 | > {"href": "hsdshdflab.hdfgroup.org/datatypes", "rel": "self"}, 157 | > {"href": "hsdshdflab.hdfgroup.org/groups/g-b116b6f0-85e9-11e8-9cc2-0242ac120008", "rel": "root"}, 158 | > {"href": "hsdshdflab.hdfgroup.org/", "rel": "home"} 159 | > ] 160 | > } 161 | > ``` 162 | 163 | Related Resources 164 | ----------------- 165 | 166 | - DELETE\_Datatype 167 | - GET\_Datatype 168 | - POST\_Datatype 169 | - ../DatasetOps/POST\_Dataset 170 | - ../AttrOps/PUT\_Attribute 171 | 172 | -------------------------------------------------------------------------------- /AclOps/index.rst: -------------------------------------------------------------------------------- 1 | #################### 2 | Access Control List 3 | #################### 4 | 5 | An Access Control List (ACL) is a key-value store that can be used to manage what operations can 6 | be performed by which user on group, dataset, or committed type objects. Operations on other 7 | objects (e.g. links, dataspace, or attributes) use the ACL of the object they belong to. 8 | 9 | Each ACL consists of 1 or more items in the form: 10 | 11 | (username, read, create, update, delete, readACL, updateACL) 12 | 13 | where username is a string, and read, create, update, delete, readACL and updateACL are booleans. 14 | These flags have the following semantics when the given username is provided in the http 15 | Authorization header: 16 | 17 | * read: The given user is authorized for read access to the resource (generally all GET requests) 18 | * create: The given user is authorized to create new resources (generally POST or PUT requests) 19 | * update: The given user is authorized to modified a resource (e.g. :doc:`../DatasetOps/PUT_Value`) 20 | * delete: The given user is authorized to delete a resource (e.g. Delete a Group) 21 | * readACL: The given user is authorized to read the ACLs of a resource 22 | * updateACL: The given user is authorized to modify the ACLs of a resource 23 | 24 | A special username 'default' is used to denote the access permission for all other users who 25 | are not listed in the ACL (including un-authenticated requests that don't provide a username). 26 | 27 | Example 28 | ------- 29 | 30 | Suppose a given dataset has the following ACL: 31 | 32 | ======== ==== ====== ====== ====== ======= ======== 33 | username read create update delete readACL writeACL 34 | ======== ==== ====== ====== ====== ======= ======== 35 | default true false false false false false 36 | joe true false true false false false 37 | ann true true true true true true 38 | ======== ==== ====== ====== ====== ======= ======== 39 | 40 | This ACL would enable anyone to read (perform GET requests). User 'joe' would be able 41 | to read and update (modify values in the dataset). While user 'ann' would have full 42 | control to do any operation on the dataset (including modifying permissions for herself or 43 | other users). 44 | 45 | The following unauthenticated (no HTTP Authorization header) 46 | requests on the dataset would be granted or denied as follows: 47 | 48 | * GET /datasets/ - granted (returns HTTP Status 200 - OK) 49 | * POST /datasets//value - granted (returns HTTP Status 200 - OK) 50 | * PUT /datasets//shape) - denied (returns HTTP Status 401 - Unauthorized) 51 | * PUT /datasets//attributes/ - denied (returns HTTP Status 401 - Unauthorized) 52 | * DELETE /datasets/ - denied (returns HTTP Status 401 - Unauthorized) 53 | 54 | Next the same set of requests are sent with 'joe' as the user in the HTTP Authorization header: 55 | 56 | * GET /datasets/ - granted (returns HTTP Status 200 - OK) 57 | * POST /datasets//value - granted (returns HTTP Status 200 - OK) 58 | * PUT /datasets//shape) - grant (returns HTTP Status 200 - OK) 59 | * PUT /datasets//attributes/ - denied (returns HTTP Status 403 - Forbidden) 60 | * DELETE /datasets/ - denied (returns HTTP Status 403 - Forbidden) 61 | 62 | Finally the same set of requests are sent with 'ann' as the user: 63 | 64 | * GET /datasets/ - granted (returns HTTP Status 200 - OK) 65 | * POST /datasets//value - granted (returns HTTP Status 200 - OK) 66 | * PUT /datasets//shape) - grant (returns HTTP Status 200 - OK) 67 | * PUT /datasets//attributes/ - denied (returns HTTP Status 201 - Created) 68 | * DELETE /datasets/ - denied (returns HTTP Status 200 - OK) 69 | 70 | Note: HTTP Status 401 basically says: "you can't have access until you tell me who you are", 71 | while HTTP Status 403 says: "I know who you are, but you don't have permissions to access this 72 | resource." 73 | 74 | Root ACL Inheritance 75 | -------------------- 76 | 77 | In many cases it will be desired to have a default ACL that applies to each resource in the domain. 78 | This can be accomplished by defining an ACL for the root group. This will control the access 79 | rights for any resource unless an ACL is present in that resource for the requesting user. 80 | 81 | The default ACL can be read or updated by forming a request with a uri that includes the root group id, 82 | i.e.: "/groups//acls", or by using the uri path for the domain, i.e. "/acls". 83 | 84 | 85 | For a given user then, the permissions for a resource are found in the following way: 86 | 87 | #. If the user is present in the resources ACL, those permissions are used 88 | #. If no user is present in the resources ACL, but is present in the root group, those permissions are used 89 | #. Otherwise, if a 'default' user is present in the resource ACL, those permissions are used 90 | #. If a 'default' user is not present in the resource ACL, but is present in the root ACL, those permissions are used 91 | #. If no 'default' user is present in the root ACL, the permissions defined in the 'default_acl' config is used 92 | 93 | List of Operations 94 | ------------------ 95 | 96 | .. toctree:: 97 | :maxdepth: 1 98 | 99 | GET_ACL 100 | GET_ACLs 101 | PUT_ACL 102 | 103 | 104 | -------------------------------------------------------------------------------- /DatatypeOps/POST_Datatype.md: -------------------------------------------------------------------------------- 1 | POST Datatype 2 | ============= 3 | 4 | Description 5 | ----------- 6 | 7 | Creates a new committed datatype. 8 | 9 | Requests 10 | -------- 11 | 12 | ### Syntax 13 | 14 | ``` sourceCode 15 | POST /datatypes HTTP/1.1 16 | X-Hdf-domain: DOMAIN 17 | Authorization: 18 | ``` 19 | 20 | ``` sourceCode 21 | POST /datatypes?domain=DOMAIN HTTP/1.1 22 | Authorization: 23 | ``` 24 | 25 | ### Request Parameters 26 | 27 | This implementation of the operation does not use request parameters. 28 | 29 | ### Request Headers 30 | 31 | This implementation of the operation uses only the request headers that are common to most requests. See ../CommonRequestHeaders 32 | 33 | ### Request Elements 34 | 35 | The request body must be a JSON object with a 'type' link key as described below. Optionally, the request body can include a 'link' key that describes how the new committed datatype will be linked. 36 | 37 | #### type 38 | 39 | The value of the type key can either be one of the predefined type strings (see predefined types), or a JSON representation of a type. (see ../Types/index). 40 | 41 | #### link 42 | 43 | If present, the link value must include the following subkeys: 44 | 45 | #### link\['id'\] 46 | 47 | The UUID of the group the new datatype should be linked from. If the UUID is not valid, the request will fail and a new datatype will not be created. 48 | 49 | #### link\['name'\] 50 | 51 | The name of the new link. 52 | 53 | Responses 54 | --------- 55 | 56 | ### Response Headers 57 | 58 | This implementation of the operation uses only response headers that are common to most responses. See ../CommonResponseHeaders. 59 | 60 | ### Response Elements 61 | 62 | On success, a JSON response will be returned with the following elements: 63 | 64 | #### id 65 | 66 | The UUID of the newly created datatype object. 67 | 68 | #### root 69 | 70 | The root group of the domain which the datatype is within. 71 | 72 | #### attributeCount 73 | 74 | The number of attributes belonging to the datatype. 75 | 76 | #### created 77 | 78 | A timestamp giving the time the datatype was created in UTC (ISO-8601 format). 79 | 80 | #### lastModified 81 | 82 | A timestamp giving the most recent time the datatype has been modified (i.e. attributes or links updated) in UTC (ISO-8601 format). 83 | 84 | ### Special Errors 85 | 86 | This implementation of the operation does not return special errors. For general information on standard error codes, see ../CommonErrorResponses. 87 | 88 | Examples 89 | -------- 90 | 91 | ### Sample Request 92 | 93 | Create a new committed datatype using the "H5T\_IEEE\_F32LE" (32-bit float) predefined type. 94 | 95 | ``` sourceCode 96 | POST /datatypes HTTP/1.1 97 | Host: hsdshdflab.hdfgroup.org 98 | X-Hdf-domain: /shared/tall.h5 99 | Content-Length: 26 100 | Accept: */* 101 | Accept-Encoding: gzip, deflate 102 | ``` 103 | 104 | ``` sourceCode 105 | { 106 | "type": "H5T_IEEE_F32LE" 107 | } 108 | ``` 109 | 110 | ### Sample cURL command 111 | 112 | ``` sourceCode 113 | $ curl -X POST -u username:password --header "X-Hdf-domain: /shared/tall.h5" --header "Content-Type: application/json" 114 | -d "{\"type\": \"H5T_IEEE_F32LE\"}" hsdshdflab.hdfgroup.org/datatypes 115 | ``` 116 | 117 | ### Sample Response 118 | 119 | ``` sourceCode 120 | HTTP/1.1 201 Created 121 | Date: Fri, 13 Jul 2018 15:35:49 GMT 122 | Content-Length: 186 123 | Content-Type: application/json 124 | Server: nginx/1.15.0 125 | ``` 126 | 127 | ``` sourceCode 128 | { 129 | "id": "t-6b0bdf9a-86b2-11e8-89f2-0242ac120009", 130 | "created": 1531496149.3141127, 131 | "root": "g-b116b6f0-85e9-11e8-9cc2-0242ac120008", 132 | "lastModified": 1531496149.3141127, 133 | "attributeCount": 0 134 | } 135 | ``` 136 | 137 | ### Sample Request with Link 138 | 139 | Create a new committed datatype and link to root (id "g-b116b6f0-...") as "linked\_dtype". 140 | 141 | ``` sourceCode 142 | POST /datatypes HTTP/1.1 143 | Host: hsdshdflab.hdfgroup.org 144 | X-Hdf-domain: /shared/tall.h5 145 | Content-Length: 108 146 | Accept: */* 147 | Accept-Encoding: gzip, deflate 148 | ``` 149 | 150 | ``` sourceCode 151 | { 152 | "type": "H5T_IEEE_F64LE", 153 | "link": { 154 | "id": "g-b116b6f0-85e9-11e8-9cc2-0242ac120008", 155 | "name": "linked_dtype" 156 | } 157 | } 158 | ``` 159 | 160 | ### Sample cURL command 161 | 162 | ``` sourceCode 163 | $ curl -X POST -u username:password --header "X-Hdf-domain: /shared/tall.h5" --header "Content-Type: application/json" 164 | -d "{\"type\": \"H5T_IEEE_F64LE\", \"link\": {\"id\": \"g-b116b6f0-85e9-11e8-9cc2-0242ac120008\", \"name\": \"linked_dtype\"}}" hsdshdflab.hdfgroup.org/datatypes 165 | ``` 166 | 167 | ### Sample Response with Link 168 | 169 | ``` sourceCode 170 | HTTP/1.1 201 Created 171 | Date: Fri, 13 Jul 2018 15:41:44 GMT 172 | Content-Length: 186 173 | Content-Type: application/json 174 | Server: nginx/1.15.0 175 | ``` 176 | 177 | ``` sourceCode 178 | { 179 | "id": "t-3e37ab7e-86b3-11e8-bce3-0242ac12000c", 180 | "root": "g-b116b6f0-85e9-11e8-9cc2-0242ac120008", 181 | "attributeCount": 0, 182 | "created": 1531496503.6064572, 183 | "lastModified": 1531496503.6064572 184 | } 185 | ``` 186 | 187 | Related Resources 188 | ----------------- 189 | 190 | - DELETE\_Datatype 191 | - GET\_Datatype 192 | - GET\_Datatypes 193 | - ../DatasetOps/POST\_Dataset 194 | - ../AttrOps/PUT\_Attribute 195 | 196 | --------------------------------------------------------------------------------