diff --git a/AttrOps/DELETE_Attribute.rst b/AttrOps/DELETE_Attribute.rst index 8e289d2..3ea5a11 100644 --- a/AttrOps/DELETE_Attribute.rst +++ b/AttrOps/DELETE_Attribute.rst @@ -4,7 +4,8 @@ DELETE Attribute Description =========== -The implementation of the DELETE operation deletes the attribute named in the URI. +The implementation of the DELETE operation deletes the attribute named in the URI. For attributes with +names containing '/' or '#', :docs:`DELETE_Attributes` must be used. Requests ======== @@ -49,7 +50,10 @@ Syntax Request Parameters ------------------ -This implementation of the operation does not use request parameters. + +domain +^^^^^ +The domain containing the attribute's parent object. This parameter is optional if the domain is specified in the request headers. Request Headers --------------- @@ -119,6 +123,7 @@ Sample Response Related Resources ================= +* :docs:`DELETE_Attributes` * :doc:`GET_Attributes` * :doc:`GET_Attribute` * :doc:`../DatasetOps/GET_Dataset` diff --git a/AttrOps/DELETE_Attributes.rst b/AttrOps/DELETE_Attributes.rst new file mode 100644 index 0000000..c8e7262 --- /dev/null +++ b/AttrOps/DELETE_Attributes.rst @@ -0,0 +1,151 @@ +********************************************** +DELETE Attributes +********************************************** + +Description +=========== +Delete a collection of attributes specified by name as a parameter. + +======== + +Syntax +------ +.. code-block:: http + + DELETE /groups//attributes?attr_names=//.../ HTTP/1.1 + X-Hdf-domain: DOMAIN + Authorization: + +.. code-block:: http + + DELETE /groups//attributes?separator=:&attr_names=::...: HTTP/1.1 + X-Hdf-domain: DOMAIN + Authorization: + +.. code-block:: http + + DELETE /datasets//attributes?attr_names=//.../ HTTP/1.1 + X-Hdf-domain: DOMAIN + Authorization: + +.. code-block:: http + + DELETE /datasets//attributes?separator=:&attr_names=::...: HTTP/1.1 + X-Hdf-domain: DOMAIN + Authorization: + +.. code-block:: http + + DELETE /datatypes//attributes?attr_names=//.../ HTTP/1.1 + X-Hdf-domain: DOMAIN + Authorization: + +.. code-block:: http + + DELETE /datatypes//attributes?separator=:&attr_names=::...: HTTP/1.1 + X-Hdf-domain: DOMAIN + Authorization: + + +* ** is the UUID of the dataset/group/committed datatype +* ** is the url-encoded name of a requested attribute + +Request Parameters +------------------ + +This operation requires the parameter `attr_names` to specify the attributes to delete. Other parameters are optional. + +attr_names +^^^^^ +The names of the attributes to delete, as a single query parameter. Each individual attribute name is separated by a separator string. This parameter is required. + +separator +^^^^^ +The string that separates individual attribute names in the `attr_names` parameter. This parameter is optional, with a default value of `/`. + +domain +^^^^^ +The domain containing the attributes' parent object. This parameter is optional if the domain is specified in the request headers. + +encoding +^^^^^ +The type of encoding used for the attribute names. This parameter is optional. + +Request Headers +--------------- +This implementation of the operation uses only the request headers that are common +to most requests. See :doc:`../CommonRequestHeaders` + +Responses +========= + +Response Headers +---------------- + +This implementation of the operation uses only response headers that are common to +most responses. See :doc:`../CommonResponseHeaders`. + +Response Elements +----------------- + +On success, a JSON response will be returned with the following elements: + +hrefs +^^^^^ +An array of links to related resources. See :doc:`../Hypermedia`. + +Special Errors +-------------- + +This implementation of the operation does not return special errors. For general +information on standard error codes, see :doc:`../CommonErrorResponses`. + +Examples +======== + +Sample Request +-------------- + +.. code-block:: http + + DELETE /groups/g-45f464d8-883e-11e8-a9dc-0242ac12000e/attributes/?attr_names=attr1/attr2/attr3 HTTP/1.1 + Host: hsdshdflab.hdfgroup.org + X-Hdf-domain: /shared/tall.h5 + Accept: */* + Accept-Encoding: gzip, deflate + +Sample cURL command +------------------- + +.. code-block:: bash + + $ curl -X DELETE -u username:password --header "X-Hdf-domain: /shared/tall.h5" hsdshdflab.hdfgroup.org/groups/g-45f464d8-883e-11e8-a9dc-0242ac12000e/attributes/?attr_names=attr1/attr2/attr3 + +Sample Response +--------------- + +.. code-block:: http + + HTTP/1.1 200 OK + Date: Sun, 15 Jul 2018 16:06:54 GMT + Content-Length: 13 + Content-Type: application/json + Server: nginx/1.15.0 + +.. code-block:: json + + {"hrefs": []} + +Related Resources +================= + +* :doc:`DELETE_Attribute` +* :doc:`GET_Attributes` +* :doc:`GET_Attribute` +* :doc:`../DatasetOps/GET_Dataset` +* :doc:`../DatatypeOps/GET_Datatype` +* :doc:`../GroupOps/GET_Group` +* :doc:`PUT_Attribute` + + + \ No newline at end of file diff --git a/AttrOps/GET_Attribute.rst b/AttrOps/GET_Attribute.rst index 71ecf89..ed7d556 100644 --- a/AttrOps/GET_Attribute.rst +++ b/AttrOps/GET_Attribute.rst @@ -58,7 +58,26 @@ where: Request Parameters ------------------ -This implementation of the operation does not use request parameters. + +domain +^^^^^ +The domain containing the attribute's parent object. This +parameter is optional if the domain is specified in the request headers. + +ignore_nan +^^^^^ +This parameter specifies whether to replace NaN values in retrieved data +with None instances. This parameter is optional and defaults to false. + +IncludeData +^^^^^ +This parameter specifies whether to return the data of the attributein +addition to the metadata. This parameter is optional and defaults to true. + +encoding +^^^^^ +What encoding the attribute is stored in. This parameter is optional, +and defaults to no encoding. Request Headers --------------- @@ -175,6 +194,7 @@ Related Resources ================= * :doc:`DELETE_Attribute` +* :doc:`GET_AttributeValue` * :doc:`GET_Attributes` * :doc:`../DatasetOps/GET_Dataset` * :doc:`../DatatypeOps/GET_Datatype` diff --git a/AttrOps/GET_AttributeValue.rst b/AttrOps/GET_AttributeValue.rst new file mode 100644 index 0000000..b595220 --- /dev/null +++ b/AttrOps/GET_AttributeValue.rst @@ -0,0 +1,199 @@ +********************************************** +GET AttributeValue +********************************************** + +Description +=========== +Gets the value of a specified attribute of a dataset, group, or committed datatype. + +Requests +======== + +Syntax +------ + +To get the value of an attribute of a group: + +.. code-block:: http + + GET /groups//attributes//value HTTP/1.1 + X-Hdf-domain: DOMAIN + Authorization: + +.. code-block:: http + + GET /groups//attributes//value?domain=DOMAIN HTTP/1.1 + Authorization: + +To get the value of an attribute of a dataset: + +.. code-block:: http + + GET /datasets//attributes//value HTTP/1.1 + X-Hdf-domain: DOMAIN + Authorization: + +.. code-block:: http + + GET /datasets//attributes//value?domain=DOMAIN HTTP/1.1 + Authorization: + +To get the value of an attribute of a datatype: + +.. code-block:: http + + GET /datatypes//attributes//value HTTP/1.1 + X-Hdf-domain: DOMAIN + Authorization: + +.. code-block:: http + + GET /datatypes//attributes//value?domain=DOMAIN HTTP/1.1 + Authorization: + +where: + +* ** is the UUID of the dataset/group/committed datatype +* ** is the url-encoded name of the requested attribute + +Request Parameters +------------------ + +domain +^^^^^ +The domain containing the attribute's parent object. This +parameter is optional if the domain is specified in the request headers. + +ignore_nan +^^^^^ +This parameter specifies whether to replace NaN values in retrieved data +with None instances. This parameter is optional and defaults to false. + +IncludeData +^^^^^ +This parameter specifies whether to return the data of the attribute in +addition to the metadata. This parameter is optional and defaults to true. + +encoding +^^^^^ +What encoding the attribute is stored in. This parameter is optional, +and defaults to no encoding. + +Request Headers +--------------- +This implementation of the operation uses only the request headers that are common +to most requests. See :doc:`../CommonRequestHeaders` + +Responses +========= + +Response Headers +---------------- + +This implementation of the operation uses only response headers that are common to +most responses. See :doc:`../CommonResponseHeaders`. + +Response Elements +----------------- + +On success, a JSON response will be returned with the following elements: + +type +^^^^ +A JSON object representing the type of the attribute. See :doc:`../Types/index` for +details of the type representation. + +shape +^^^^^ + +A JSON object that represents the dataspace of the attribute. Subkeys of shape are: + +class: A string with one of the following values: + + * H5S_NULL: A null dataspace, which has no elements + * H5S_SCALAR: A dataspace with a single element (although possibly of a complex datatype) + * H5S_SIMPLE: A dataspace that consists of a regular array of elements + +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. + +value +^^^^^ +A JSON array (or string or number for scalar datasets) giving the values of the requested +attribute. + +hrefs +^^^^^ +An array of links to related resources. See :doc:`../Hypermedia`. + +.. + TODO - Encoding for encoded attributes? + +Special Errors +-------------- + +This implementation of the operation does not return special errors. For general +information on standard error codes, see :doc:`../CommonErrorResponses`. + +Examples +======== + +Sample Request +-------------- + +Get the value of an attribute named "attr1" from a group with UUID: "g-be5996fa-...". + +.. code-block:: http + + GET /groups/g-6e51a375-8f3c0647-be19-aaa940-fa2484/attributes/attr1/value HTTP/1.1 + Host: hsdshdflab.hdfgroup.org + X-Hdf-domain: /shared/tall.h5 + Accept-Encoding: gzip, deflate + Accept: */* + +Sample cURL command +------------------- + +.. code-block:: bash + + $ curl -X GET --header "X-Hdf-domain: /shared/tall.h5" hsdshdflab.hdfgroup.org/groups/g-6e51a375-8f3c0647-be19-aaa940-fa2484/attributes/attr1/value + +Sample Response +--------------- + +.. code-block:: http + + HTTP/1.1 200 OK + Date: Sun, 15 Jul 2018 16:17:44 GMT + Content-Length: 522 + Etag: "55b2e2ce2d3a2449a49cfd76c4dae635ec43a150" + Content-Type: application/json + Server: nginx/1.15.0 + +.. code-block:: json + +{ + 'value': [0, 1, 2, 3, 4, 5], + 'hrefs': + [ + {'rel': 'self', 'href': 'http://localhost:5101/groups/g-6e51a375-8f3c0647-be19-aaa940-fa2484/attributes/attr1'}, + {'rel': 'home', 'href': 'http://localhost:5101/'}, + {'rel': 'owner', 'href': 'http://localhost:5101/groups/g-6e51a375-8f3c0647-be19-aaa940-fa2484'} + ] +} + + +Related Resources +================= + +* :doc:`DELETE_Attribute` +* :doc:`GET_Attribute` +* :doc:`GET_Attributes` +* :doc:`../DatasetOps/GET_Dataset` +* :doc:`../DatatypeOps/GET_Datatype` +* :doc:`../GroupOps/GET_Group` +* :doc:`PUT_Attribute` + + + \ No newline at end of file diff --git a/AttrOps/GET_Attributes.rst b/AttrOps/GET_Attributes.rst index 5d81d98..325d478 100644 --- a/AttrOps/GET_Attributes.rst +++ b/AttrOps/GET_Attributes.rst @@ -6,7 +6,7 @@ Description =========== Gets all the attributes of a dataset, group, or committed datatype. For each attribute the request returns the attribute's name, type, and shape. To get -the attribute data use :doc:`GET_Attribute`. +the attribute data use the parameter `IncludeData` or :doc:`GET_Attribute`. Requests ======== @@ -59,7 +59,7 @@ where: Request Parameters ------------------ -This implementation of the operation uses the following request parameters (both +This implementation of the operation uses the following request parameters (all optional): Limit @@ -72,6 +72,31 @@ If provided, a string value indicating that only attributes that occur after the marker value will be returned. *Note:* the marker expression should be url-encoded. +domain +^^^^^ +The domain containing the attribute's parent object. This +parameter is optional if the domain is specified in the request headers. + +ignore_nan +^^^^^ +This parameter specifies whether to replace NaN values in retrieved data +with None instances. This parameter is optional and defaults to false. + +IncludeData +^^^^^ +This parameter specifies whether to return the data of the attributein +addition to the metadata. This parameter is optional and defaults to true. + +encoding +^^^^^ +What encoding the attribute is stored in. This parameter is optional, +and defaults to no encoding. + +CreateOrder +^^^^^ +Whether the attributes should be returned in their relative order of creation. +This parameter is optional and defaults to false. + Request Headers --------------- This implementation of the operation uses only the request headers that are common diff --git a/AttrOps/POST_Attributes.rst b/AttrOps/POST_Attributes.rst new file mode 100644 index 0000000..5f54891 --- /dev/null +++ b/AttrOps/POST_Attributes.rst @@ -0,0 +1,334 @@ +********************************************** +POST Attributes +********************************************** + +Description +=========== +Gets a collection of attributes from a dataset, group, or committed datatype. +For each attribute the request returns the attribute's name, type, and shape. To get +the attribute data use the parameter `IncludeData`. + +Requests +======== + +Syntax +------ + +To get the attributes of a group: + +.. code-block:: http + + POST /groups//attributes HTTP/1.1 + X-Hdf-domain: DOMAIN + Authorization: + +.. code-block:: http + + POST /groups//attributes?domain=DOMAIN HTTP/1.1 + Authorization: + +To get the attributes of a dataset: + +.. code-block:: http + + POST /datasets//attributes HTTP/1.1 + X-Hdf-domain: DOMAIN + Authorization: + +.. code-block:: http + + POST /datasets//attributes?domain=DOMAIN HTTP/1.1 + Authorization: + +To get the attributes of a datatype: + +.. code-block:: http + + POST /datatypes//attributes HTTP/1.1 + X-Hdf-domain: DOMAIN + Authorization: + +.. code-block:: http + + POST /datatypes//attributes?domain=DOMAIN HTTP/1.1 + Authorization: + +where: + +* ** is the UUID of the dataset/group/committed datatype + +Request Parameters +------------------ +A collection of attributes to be read must be provided in one of two ways. + +If the same attributes are to be read from each target object, the attributes' +names should be provided under `attr_names`. + +If each target object has a unique set of attributes which you wish to read, then +the target attribute names should be provided as the value of each key within the +dictionary `obj_ids`. + +attr_names +^^^^^ +The names of the attributes which should be read from the target object(s). +This parameter is used when the same attributes are to be read from all +target objects. + +obj_ids +^^^^^ +The collection of objects to read attributes from. + +If the same attribute names are to be read from all objects, `obj_ids` is a list. + +If each target object has a different set of attributes which should be read from it, `obj_ids` is +a dictionary mapping each target object id to the names of the attributes to read from it. + +domain +^^^^^ +The domain containing the attributes' parent object. This +parameter is optional if the domain is specified in the request headers. + +ignore_nan +^^^^^ +This parameter specifies whether to replace NaN values in retrieved data +with None instances. This parameter is optional and defaults to false. + +IncludeData +^^^^^ +This parameter specifies whether to return the data of the attributes in +addition to the metadata. This parameter is optional and defaults to true. + +encoding +^^^^^ +What encoding the attributes are stored in. This parameter is optional, +and defaults to no encoding. + +Request Headers +--------------- +This implementation of the operation uses only the request headers that are common +to most requests. See :doc:`../CommonRequestHeaders` + +Responses +========= + +Response Headers +---------------- + +This implementation of the operation uses only response headers that are common to +most responses. See :doc:`../CommonResponseHeaders`. + +Response Elements +----------------- + +On success, a JSON response will be returned with the following elements: + + +attributes +^^^^^^^^^^ + +An array of JSON objects with an element for each returned attribute. +Each element will have keys: name, type, shape, created, and lastModified. See +:doc:`POST_Attribute` for a description of these keys. + +hrefs +^^^^^ +An array of links to related resources. See :doc:`../Hypermedia`. + +Special Errors +-------------- + +This implementation of the operation does not return special errors. For general +information on standard error codes, see :doc:`../CommonErrorResponses`. + +Examples +======== + +Sample Request +-------------- + +Get attributes of a group with UUID: "1a956e54-...". + +.. code-block:: http + + POST /groups/g-be5996fa-83c5-11e8-a8e6-0242ac120016/attributes HTTP/1.1 + Host: hsdshdflab.hdfgroup.org + X-Hdf-domain: /shared/tall.h5 + Accept-Encoding: gzip, deflate + Accept: */* + +Sample cURL command +------------------- + +.. code-block:: bash + + $ curl -X POST --header "X-Hdf-domain: /shared/tall.h5" hsdshdflab.hdfgroup.org/groups/g-be5996fa-83c5-11e8-a8e6-0242ac120016/attributes + +Sample Response +--------------- + +.. code-block:: http + + HTTP/1.1 200 OK + Date: Sun, 15 Jul 2018 16:23:43 GMT + Content-Length: 797 + Etag: "7cbeefcf8d9997a8865bdea3bf2d541a14e9bf71" + Content-Type: application/json + Server: nginx/1.15.0 + +.. code-block:: json + + { + "attributes": [ + { + "type": { + "base": "H5T_STD_I8LE", + "class": "H5T_INTEGER" + }, + "name": "attr1", + "shape": { + "dims": [10], + "class": "H5S_SIMPLE" + }, + "created": 1531174596.117736, + "href": "hsdshdflab.hdfgroup.org/groups/g-be5996fa-83c5-11e8-a8e6-0242ac120016/attributes/attr1" + }, + { + "type": { + "base": "H5T_STD_I32BE", + "class": "H5T_INTEGER" + }, + "name": "attr2", + "shape": { + "dims": [2, 2], + "class": "H5S_SIMPLE" + }, + "created": 1531174596.141592, + "href": "hsdshdflab.hdfgroup.org/groups/g-be5996fa-83c5-11e8-a8e6-0242ac120016/attributes/attr2" + } + ], + "hrefs": [ + {"href": "hsdshdflab.hdfgroup.org/groups/g-be5996fa-83c5-11e8-a8e6-0242ac120016/attributes", "rel": "self"}, + {"href": "hsdshdflab.hdfgroup.org/", "rel": "home"}, + {"href": "hsdshdflab.hdfgroup.org/groups/g-be5996fa-83c5-11e8-a8e6-0242ac120016", "rel": "owner"} + ] + } + +Sample Request - get Batch +--------------------------- + +Get the five attributes that occur after attribute "attr2" from a group with UUID: +"g-45f464d8-...". + +.. code-block:: http + + POST /groups/g-45f464d8-883e-11e8-a9dc-0242ac12000e/attributes?Marker=attr2&Limit=5 HTTP/1.1 + Host: hsdshdflab.hdfgroup.org + X-Hdf-domain: /shared/tall.h5 + Accept-Encoding: gzip, deflate + Accept: */* + +Sample cURL command +------------------- + +.. code-block:: bash + + $ curl -X POST --header "X-Hdf-domain: /shared/tall.h5" "hsdshdflab.hdfgroup.org/groups/g-45f464d8-883e-11e8-a9dc-0242ac12000e/attributes?Marker=attr2&Limit=5" + +Sample Response - get Batch +--------------------------- + +.. code-block:: http + + HTTP/1.1 200 OK + Date: Sun, 15 Jul 2018 16:38:16 GMT + Content-Length: 1767 + Etag: "9483f4356e08d12b719aa64ece09e659b05adaf2" + Content-Type: application/json + Server: nginx/1.15.0 + +.. code-block:: json + + { + "attributes": [ + { + "name": "attr3", + "type": { + "base": "H5T_STD_U32BE", + "class": "H5T_INTEGER" + }, + "shape": { + "class": "H5S_SCALAR" + }, + "created": 1531672545.5978162, + "href": "hsdshdflab.hdfgroup.org/groups/g-45f464d8-883e-11e8-a9dc-0242ac12000e/attributes/attr3" + }, + { + "name": "attr4", + "type": { + "base": "H5T_STD_I32LE", + "class": "H5T_INTEGER" + }, + "shape": { + "class": "H5S_SCALAR" + }, + "created": 1531667223.0914037, + "href": "hsdshdflab.hdfgroup.org/groups/g-45f464d8-883e-11e8-a9dc-0242ac12000e/attributes/attr4" + }, + { + "name": "attr5", + "type": { + "base": "H5T_STD_U64LE", + "class": "H5T_INTEGER" + }, + "shape": { + "class": "H5S_SCALAR" + }, + "created": 1531672562.6758137, + "href": "hsdshdflab.hdfgroup.org/groups/g-45f464d8-883e-11e8-a9dc-0242ac12000e/attributes/attr5" + }, + { + "name": "attr6", + "type": { + "strPad": "H5T_STR_NULLPAD", + "charSet": "H5T_CSET_ASCII", + "class": "H5T_STRING", + "length": 40 + }, + "shape": { + "class": "H5S_SIMPLE", + "dims": [2] + }, + "created": 1531668943.5116098, + "href": "hsdshdflab.hdfgroup.org/groups/g-45f464d8-883e-11e8-a9dc-0242ac12000e/attributes/attr6" + }, + { + "name": "attr7", + "type": { + "base": "H5T_STD_U64LE", + "class": "H5T_INTEGER" + }, + "shape": { + "class": "H5S_SCALAR" + }, + "created": 1531672573.915442, + "href": "hsdshdflab.hdfgroup.org/groups/g-45f464d8-883e-11e8-a9dc-0242ac12000e/attributes/attr7" + } + ], + "hrefs": [ + {"href": "hsdshdflab.hdfgroup.org/groups/g-45f464d8-883e-11e8-a9dc-0242ac12000e/attributes", "rel": "self"}, + {"href": "hsdshdflab.hdfgroup.org/", "rel": "home"}, + {"href": "hsdshdflab.hdfgroup.org/groups/g-45f464d8-883e-11e8-a9dc-0242ac12000e", "rel": "owner"} + ] + } + +Related Resources +================= + +* :doc:`DELETE_Attribute` +* :doc:`POST_Attributes` +* :doc:`../DatasetOps/POST_Dataset` +* :doc:`../DatatypeOps/POST_Datatype` +* :doc:`../GroupOps/POST_Group` +* :doc:`PUT_Attribute` + + diff --git a/AttrOps/PUT_Attribute.rst b/AttrOps/PUT_Attribute.rst index ce08e7e..a318fcc 100644 --- a/AttrOps/PUT_Attribute.rst +++ b/AttrOps/PUT_Attribute.rst @@ -6,7 +6,7 @@ Description =========== Creates a new attribute in a group, dataset, or committed datatype. -*Note*: The new attribute will replace any existing attribute with the same name. +*Note*: The new attribute will replace any existing attribute with the same name if the `replace` parameter is provided. Requests ======== @@ -58,7 +58,18 @@ To create a committed datatype attribute: Request Parameters ------------------ -This implementation of the operation does not use request parameters. + +This implementation of the operation uses several request parameters, all optional: + +replace +^^^^^ +Whether existing attributes on the same name on the target object should be replaced. If such an attribute already exists and `replace` is false, +the request will fail with code 409. This parameter is optional and defaults to false. + +domain +^^^^^ +The domain containing the attribute's parent object. This +parameter is optional if the domain is specified in the request headers. Request Headers --------------- @@ -218,6 +229,9 @@ Sample Response - string attribute Content-Type: application/json Server: nginx/1.15.0 +.. + TODO + .. code-block:: json {"hrefs": []} @@ -272,6 +286,8 @@ Sample Response - compound type Content-Length: 13 Content-Type: application/json Server: nginx/1.15.0 +.. + TODO .. code-block:: json diff --git a/AttrOps/PUT_AttributeValue.rst b/AttrOps/PUT_AttributeValue.rst new file mode 100644 index 0000000..1718dd7 --- /dev/null +++ b/AttrOps/PUT_AttributeValue.rst @@ -0,0 +1,274 @@ +********************************************** +PUT AttributeValue +********************************************** + +Description +=========== +Update the value of an attribute in a group, dataset, or committed datatype. + +Requests +======== + +Syntax +------ + +To update the value of a group attribute: + +.. code-block:: http + + PUT /groups//attributes//value HTTP/1.1 + X-Hdf-domain: DOMAIN + Authorization: + +.. code-block:: http + + PUT /groups//attributes//value?domain=DOMAIN HTTP/1.1 + Authorization: + +To update the value of a dataset attribute: + +.. code-block:: http + + PUT /datasets//attributes//value HTTP/1.1 + X-Hdf-domain: DOMAIN + Authorization: + +.. code-block:: http + + PUT /datasets//attributes//value?domain=DOMAIN HTTP/1.1 + Authorization: + +To update the value of a committed datatype attribute: + +.. code-block:: http + + PUT /datatypes//attributes//value HTTP/1.1 + X-Hdf-domain: DOMAIN + Authorization: + +.. code-block:: http + + PUT /datatypes//attributes//value?domain=DOMAIN HTTP/1.1 + Authorization: + +* ** is the UUID of the dataset/group/committed datatype +* ** is the url-encoded name of the requested attribute + +Request Parameters +------------------ + +This implementation of the operation uses several request parameters, all optional: + +domain +^^^^^ +The domain containing the attribute's parent object. This +parameter is optional if the domain is specified in the request headers. + +Request Headers +--------------- +This implementation of the operation uses only the request headers that are common +to most requests. See :doc:`../CommonRequestHeaders` + +Request Elements +---------------- + +The request body must include a JSON object with a 'value' key. The request body +may include an optional `encoding` parameter. + +value +^^^^^ + +A JSON array (or number or string for scalar attributes with primitive types) that +specifies the new values for the attribute. The elements of the array must be +compatible with the type of the attribute. +Not valid to provide if the shape is ``H5S_NULL``. + + +encoding +^^^^^ +Specifies the encoding that the new attribute value is in. Defaults to `None`. + +Responses +========= + +Response Headers +---------------- + +This implementation of the operation uses only response headers that are common to +most responses. See :doc:`../CommonResponseHeaders`. + +Response Elements +----------------- + +On success, a JSON response will be returned with the following elements: + +hrefs +^^^^^ +An array of links to related resources. See :doc:`../Hypermedia`. + +Special Errors +-------------- + +This implementation of the operation does not return special errors. For general +information on standard error codes, see :doc:`../CommonErrorResponses`. + +Examples +======== + +Sample Request - scalar attribute +---------------------------------- + +Create an integer scalar attribute in the group with UUID of "g-45f464d8-" named "attr4". +The value of the attribute will be 42. + +.. code-block:: http + + PUT /groups/g-45f464d8-883e-11e8-a9dc-0242ac12000e/attributes/attr4/value HTTP/1.1 + Host: hsdshdflab.hdfgroup.org + X-Hdf-domain: /shared/tall.h5 + Content-Length: 38 + Accept: */* + Accept-Encoding: gzip, deflate + + +.. code-block:: json + + { + "value": 42 + } + +Sample cURL command +------------------- + +.. code-block:: bash + + $ curl -X PUT -u username:password --header "X-Hdf-domain: /shared/tall.h5" --header "Content-Type: application/json" + -d "{\"type\": \"H5T_STD_I32LE\",\"value\": 42}" hsdshdflab.hdfgroup.org/groups/g-45f464d8-883e-11e8-a9dc-0242ac12000e/attributes/attr4/value + +Sample Response - scalar attribute +----------------------------------- + +.. code-block:: http + + HTTP/1.1 201 Created + Date: Sun, 15 Jul 2018 15:07:03 GMT + Content-Length: 13 + Content-Type: application/json + Server: nginx/1.15.0 + +.. code-block:: json + + {"hrefs": []} + +Sample Request - string attribute +---------------------------------- + +Create a two-element, fixed width string attribute in the group with UUID of +"g-45f464d8-" named "attr6". +The attributes values will be "Hello, ..." and "Goodbye!". + +.. code-block:: http + + PUT /groups/g-45f464d8-883e-11e8-a9dc-0242ac12000e/attributes/attr6/value HTTP/1.1 + Host: hsdshdflab.hdfgroup.org + X-Hdf-domain: /shared/tall.h5 + Content-Length: 178 + Accept: */* + Accept-Encoding: gzip, deflate + +.. code-block:: json + + { + "value": ["Hello, I'm a fixed-width string!", "Goodbye!"] + } + +Sample cURL command +------------------- + +.. code-block:: bash + + $ curl -X PUT -u username:password --header "X-Hdf-domain: /shared/tall.h5" --header "Content-Type: application/json" + -d "{\"shape\": [2], \"type\": {\"class\": \"H5T_STRING\", \"charSet\": \"H5T_CSET_ASCII\", \"strPad\": \"H5T_STR_NULLPAD\", \"length\": 40}, + \"value\": [\"Hello, I'm a fixed-width string"'!'"\", \"Goodbye"'!'"\"]}" hsdshdflab.hdfgroup.org/groups/g-45f464d8-883e-11e8-a9dc-0242ac12000e/attributes/attr6/value + +Sample Response - string attribute +----------------------------------- + +.. code-block:: http + + HTTP/1.1 201 Created + Date: Sun, 15 Jul 2018 15:35:43 GMT + Content-Length: 13 + Content-Type: application/json + Server: nginx/1.15.0 + +.. + TODO + +.. code-block:: json + + {"hrefs": []} + +Sample Request - compound type +---------------------------------- + +Create a two-element, attribute in the group with UUID of +"g-45f464d8-" named "attr_compound". The attribute has a compound type with an integer +and a floating point element. + +.. code-block:: http + + PUT /groups/g-45f464d8-883e-11e8-a9dc-0242ac12000e/attributes/attr_compound/value HTTP/1.1 + Host: hsdshdflab.hdfgroup.org + X-Hdf-domain: /shared/tall.h5 + Content-Length: 187 + Accept: */* + Accept-Encoding: gzip, deflate + +.. code-block:: json + + + { + "value": [[55, 32.34], [59, 29.34]] + } + +Sample cURL command +------------------- + +.. code-block:: bash + + $ curl -X PUT -u username:password --header "X-Hdf-domain: /shared/tall.h5" --header "Content-Type: application/json" + -d "{\"shape\": 2, \"type\": {\"class\": \"H5T_COMPOUND\", \"fields\": [{\"type\": \"H5T_STD_I32LE\", \"name\": \"temp\"}, + {\"type\": \"H5T_IEEE_F32LE\", \"name\": \"pressure\"}]}, \"value\": [[55, 32.34], [59, 29.34]]}" hsdshdflab.hdfgroup.org/groups/g-45f464d8-883e-11e8-a9dc-0242ac12000e/attributes/attr_compound/value + +Sample Response - compound type +----------------------------------- + +.. code-block:: http + + HTTP/1.1 201 Created + Date: Sun, 15 Jul 2018 15:43:00 GMT + Content-Length: 13 + Content-Type: application/json + Server: nginx/1.15.0 +.. + TODO + +.. code-block:: json + + {"hrefs": []} + + + +Related Resources +================= + +* :doc:`DELETE_Attribute` +* :doc:`GET_Attribute` +* :doc:`GET_Attributes` +* :doc:`../DatasetOps/GET_Dataset` +* :doc:`../DatatypeOps/GET_Datatype` +* :doc:`../GroupOps/GET_Group` + + + diff --git a/AttrOps/PUT_Attributes.rst b/AttrOps/PUT_Attributes.rst new file mode 100644 index 0000000..62b7e6a --- /dev/null +++ b/AttrOps/PUT_Attributes.rst @@ -0,0 +1,333 @@ +********************************************** +PUT Attributes +********************************************** + +Description +=========== +Creates a collections of new attributes in a group, dataset, or committed datatype. + +*Note*: The new attributes will replace any existing attributes with the same names if the `replace` parameter is provided. + +Requests +======== + +Syntax +------ + +To create a collection of group attributes: + +.. code-block:: http + + PUT /groups//attributes/ HTTP/1.1 + X-Hdf-domain: DOMAIN + Authorization: + +.. code-block:: http + + PUT /groups//attributes/?domain=DOMAIN HTTP/1.1 + Authorization: + +To create a collection of dataset attributes: + +.. code-block:: http + + PUT /datasets//attributes/ HTTP/1.1 + X-Hdf-domain: DOMAIN + Authorization: + +.. code-block:: http + + PUT /datasets//attributes/?domain=DOMAIN HTTP/1.1 + Authorization: + +To create a collection of committed datatype attributes: + +.. code-block:: http + + PUT /datatypes//attributes/ HTTP/1.1 + X-Hdf-domain: DOMAIN + Authorization: + +.. code-block:: http + + PUT /datatypes//attributes/?domain=DOMAIN HTTP/1.1 + Authorization: + +* ** is the UUID of the dataset/group/committed datatype +* ** is the url-encoded name of the requested attribute + +Request Parameters +------------------ + +This implementation of the operation uses several request parameters, all optional: + +replace +^^^^^ +Whether existing attributes on the same name on the target object should be replaced. If such an attribute already exists and `replace` is false, +the request will fail with code 409. This parameter is optional and defaults to false. + +domain +^^^^^ +The domain containing the attributes' parent objects. This +parameter is optional if the domain is specified in the request headers. + +Request Headers +--------------- +This implementation of the operation uses only the request headers that are common +to most requests. See :doc:`../CommonRequestHeaders` + +Request Elements +---------------- + +The request must provide at least one attribute to be written. This may be done in one of three ways: As +a list of attribute items named `attributes`, a dictionary `obj_ids` mapping a set of +target object ids to the attribute objects which are to be written to those +objects, or a single attribute item desribe by a `type` and optional `shape`/`value`. + +obj_ids +^^^^^ +A collection of objects to which the attributes are to be written. + +If the same set of attributes is to be written to each target object, `obj_ids` should +be a list. If each target object has a unique collection of attributes which should +be written to it, `obj_ids` should map each target object id +to a set of attributes to write to that object. + +If this is not provided, the attributes in `attr_names` will be written to the object +with the id specified in the query. + +attributes +^^^^ +A dictionary mapping the name of each new attribute to its information. Each individual +attribute is required to provide a `type`, and may optionally provide a `shape` and `value`. + +type +^^^^ + +Specifies the desired type of a single attribute to create. Either a string that is one of the +predefined type values, a UUID of a committed type, or a JSON object describing the type. +See :doc:`../Types/index` for details of the type specification. + +shape +^^^^^^ + +Specifies the desired shape of a single attribute to create. +Either a string with the value ``H5S_NULL`` or an +integer array describing the dimensions of the attribute. +If shape is not provided, a scalar attribute will be created. +If a shape value of ``H5S_NULL`` is specified a null space attribute will be created. +(Null space attributes can not contain any data values.) + +value +^^^^^ + +Specifies the desired value of a single attribute to create. +A JSON array (or number or string for scalar attributes with primitive types) that +specifies the initial values for the attribute. The elements of the array must be +compatible with the type of the attribute. +Not valid to provide if the shape is ``H5S_NULL``. + +Responses +========= + +Response Headers +---------------- + +This implementation of the operation uses only response headers that are common to +most responses. See :doc:`../CommonResponseHeaders`. + +Response Elements +----------------- + +On success, a JSON response will be returned with the following elements: + +hrefs +^^^^^ +An array of links to related resources. See :doc:`../Hypermedia`. + +Special Errors +-------------- + +This implementation of the operation does not return special errors. For general +information on standard error codes, see :doc:`../CommonErrorResponses`. + +Examples +======== + +Sample Request - scalar attribute +---------------------------------- + +Create an integer scalar attribute in the group with UUID of "g-45f464d8-" named "attr4". +The value of the attribute will be 42. + +.. code-block:: http + + PUT /groups/g-45f464d8-883e-11e8-a9dc-0242ac12000e/attributes/attr4 HTTP/1.1 + Host: hsdshdflab.hdfgroup.org + X-Hdf-domain: /shared/tall.h5 + Content-Length: 38 + Accept: */* + Accept-Encoding: gzip, deflate + + +.. code-block:: json + + { + "type": "H5T_STD_I32LE", + "value": 42 + } + +Sample cURL command +------------------- + +.. code-block:: bash + + $ curl -X PUT -u username:password --header "X-Hdf-domain: /shared/tall.h5" --header "Content-Type: application/json" + -d "{\"type\": \"H5T_STD_I32LE\",\"value\": 42}" hsdshdflab.hdfgroup.org/groups/g-45f464d8-883e-11e8-a9dc-0242ac12000e/attributes/attr4 + +Sample Response - scalar attribute +----------------------------------- + +.. code-block:: http + + HTTP/1.1 201 Created + Date: Sun, 15 Jul 2018 15:07:03 GMT + Content-Length: 13 + Content-Type: application/json + Server: nginx/1.15.0 + +.. + TODO + +.. code-block:: json + + {"hrefs": []} + +Sample Request - string attribute +---------------------------------- + +Create a two-element, fixed width string attribute in the group with UUID of +"g-45f464d8-" named "attr6". +The attributes values will be "Hello, ..." and "Goodbye!". + +.. code-block:: http + + PUT /groups/g-45f464d8-883e-11e8-a9dc-0242ac12000e/attributes/attr6 HTTP/1.1 + Host: hsdshdflab.hdfgroup.org + X-Hdf-domain: /shared/tall.h5 + Content-Length: 178 + Accept: */* + Accept-Encoding: gzip, deflate + +.. code-block:: json + + { + "shape": [2], + "type": { + "class": "H5T_STRING", + "cset": "H5T_CSET_ASCII", + "strpad": "H5T_STR_NULLPAD", + "strsize": 40 + }, + "value": ["Hello, I'm a fixed-width string!", "Goodbye!"] + } + +Sample cURL command +------------------- + +.. code-block:: bash + + $ curl -X PUT -u username:password --header "X-Hdf-domain: /shared/tall.h5" --header "Content-Type: application/json" + -d "{\"shape\": [2], \"type\": {\"class\": \"H5T_STRING\", \"charSet\": \"H5T_CSET_ASCII\", \"strPad\": \"H5T_STR_NULLPAD\", \"length\": 40}, + \"value\": [\"Hello, I'm a fixed-width string"'!'"\", \"Goodbye"'!'"\"]}" hsdshdflab.hdfgroup.org/groups/g-45f464d8-883e-11e8-a9dc-0242ac12000e/attributes/attr6 + +Sample Response - string attribute +----------------------------------- + +.. code-block:: http + + HTTP/1.1 201 Created + Date: Sun, 15 Jul 2018 15:35:43 GMT + Content-Length: 13 + Content-Type: application/json + Server: nginx/1.15.0 + +.. + TODO + +.. code-block:: json + + {"hrefs": []} + +Sample Request - compound type +---------------------------------- + +Create a two-element, attribute in the group with UUID of +"g-45f464d8-" named "attr_compound". The attribute has a compound type with an integer +and a floating point element. + +.. code-block:: http + + PUT /groups/g-45f464d8-883e-11e8-a9dc-0242ac12000e/attributes/attr_compound HTTP/1.1 + Host: hsdshdflab.hdfgroup.org + X-Hdf-domain: /shared/tall.h5 + Content-Length: 187 + Accept: */* + Accept-Encoding: gzip, deflate + +.. code-block:: json + + + { + "shape": 2, + "type": { + "class": "H5T_COMPOUND", + "fields": [ + {"type": "H5T_STD_I32LE", "name": "temp"}, + {"type": "H5T_IEEE_F32LE", "name": "pressure"} + ] + }, + "value": [[55, 32.34], [59, 29.34]] + } + +Sample cURL command +------------------- + +.. code-block:: bash + + $ curl -X PUT -u username:password --header "X-Hdf-domain: /shared/tall.h5" --header "Content-Type: application/json" + -d "{\"shape\": 2, \"type\": {\"class\": \"H5T_COMPOUND\", \"fields\": [{\"type\": \"H5T_STD_I32LE\", \"name\": \"temp\"}, + {\"type\": \"H5T_IEEE_F32LE\", \"name\": \"pressure\"}]}, \"value\": [[55, 32.34], [59, 29.34]]}" hsdshdflab.hdfgroup.org/groups/g-45f464d8-883e-11e8-a9dc-0242ac12000e/attributes/attr_compound + +Sample Response - compound type +----------------------------------- + +.. code-block:: http + + HTTP/1.1 201 Created + Date: Sun, 15 Jul 2018 15:43:00 GMT + Content-Length: 13 + Content-Type: application/json + Server: nginx/1.15.0 + +.. + TODO + +.. code-block:: json + + {"hrefs": []} + + + +Related Resources +================= + +* :doc:`DELETE_Attribute` +* :doc:`GET_Attribute` +* :doc:`GET_Attributes` +* :doc:`../DatasetOps/GET_Dataset` +* :doc:`../DatatypeOps/GET_Datatype` +* :doc:`../GroupOps/GET_Group` + + + diff --git a/AttrOps/index.rst b/AttrOps/index.rst index bf123ab..0562f96 100644 --- a/AttrOps/index.rst +++ b/AttrOps/index.rst @@ -12,27 +12,33 @@ Creating Attributes -------------------- Use :doc:`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 -:doc:`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. +with the same name, and the `replace` parameter is provided, it will be overwritten +by this request. :doc:`PUT_Attributes` can be used to create/replace a collection +of attributes on a single object. You can use :doc:`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. Reading and Writing Data ------------------------- 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 :doc:`GET_Attribute`. +Reading the data of an attribute is done by :doc:`GET_Attribute` or :doc:`GET_AttributeValue`. Listing attributes ------------------ Use :doc:`GET_Attributes` to get information about all the attributes of a group, dataset, or committed datatype. +To get information about a collection of attributes on a group, dataset, or +committed datatype, use :doc:`POST_Attributes`. + Deleting Attributes ------------------- -Use :doc:`DELETE_Attribute` to delete an attribute. +Use :doc:`DELETE_Attribute` to delete an attribute, and :doc:`DELETE_Attributes` to +delete a collection of attributes by name. :doc:`DELETE_Attributes` must be used for +attributes with names containing '/' or '#'. List of Operations ------------------ @@ -40,10 +46,13 @@ List of Operations .. toctree:: :maxdepth: 1 + DELETE_Attribute DELETE_Attribute GET_Attribute + GET_AttributeValue GET_Attributes PUT_Attribute + PUT_Attributes diff --git a/LinkOps/DELETE_Link.rst b/LinkOps/DELETE_Link.rst new file mode 100644 index 0000000..7c65e4e --- /dev/null +++ b/LinkOps/DELETE_Link.rst @@ -0,0 +1,118 @@ +********************************************** +DELETE Link +********************************************** + +Description +=========== +The implementation of the DELETE operation deletes the link named in the URI. For links with +names containing '/' or '#', :docs:`DELETE_Links` must be used. + +Requests +======== + +Syntax +------ +.. code-block:: http + + DELETE /groups// HTTP/1.1 + X-Hdf-domain: DOMAIN + Authorization: + +.. code-block:: http + + DELETE /groups/// HTTP/1.1 + Authorization: <authorization_string> + +.. code-block:: http + + DELETE /groups/<id>/<links>?domain=DOMAIN HTTP/1.1 + Authorization: <authorization_string> + +* *<id>* is the UUID of the group containing the link to delete +* *<title>* is the url-encoded name of the requested link + +Request Parameters +------------------ + +domain +^^^^^ +The domain containing the link's parent object. This parameter is optional if the domain is specified in the request headers. + +Request Headers +--------------- +This implementation of the operation uses only the request headers that are common +to most requests. See :doc:`../CommonRequestHeaders` + +Responses +========= + +Response Headers +---------------- + +This implementation of the operation uses only response headers that are common to +most responses. See :doc:`../CommonResponseHeaders`. + +Response Elements +----------------- + +On success, a JSON response will be returned with the following elements: + +hrefs +^^^^^ +An array of links to related resources. See :doc:`../Hypermedia`. + +Special Errors +-------------- + +This implementation of the operation does not return special errors. For general +information on standard error codes, see :doc:`../CommonErrorResponses`. + +Examples +======== + +Sample Request +-------------- + +.. code-block:: http + + DELETE /groups/g-45f464d8-883e-11e8-a9dc-0242ac12000e/links/lnk1 HTTP/1.1 + Host: hsdshdflab.hdfgroup.org + X-Hdf-domain: /shared/tall.h5 + Accept: */* + Accept-Encoding: gzip, deflate + +Sample cURL command +------------------- + +.. code-block:: bash + + $ curl -X DELETE -u username:password --header "X-Hdf-domain: /shared/tall.h5" hsdshdflab.hdfgroup.org/groups/g-45f464d8-883e-11e8-a9dc-0242ac12000e/links/lnk1 + +Sample Response +--------------- + +.. code-block:: http + + HTTP/1.1 200 OK + Date: Sun, 15 Jul 2018 16:06:54 GMT + Content-Length: 13 + Content-Type: application/json + Server: nginx/1.15.0 + +.. code-block:: json + + {} + +Related Resources +================= + +* :docs:`DELETE_Links` +* :doc:`GET_Links` +* :doc:`GET_Link` +* :doc:`../DatasetOps/GET_Dataset` +* :doc:`../DatatypeOps/GET_Datatype` +* :doc:`../GroupOps/GET_Group` +* :doc:`PUT_Link` + + + \ No newline at end of file diff --git a/LinkOps/DELETE_Links.rst b/LinkOps/DELETE_Links.rst new file mode 100644 index 0000000..28d30d3 --- /dev/null +++ b/LinkOps/DELETE_Links.rst @@ -0,0 +1,118 @@ +********************************************** +DELETE Links +********************************************** + +Description +=========== +Delete a collection of links specified by name as a parameter. + +======== + +Syntax +------ +.. code-block:: http + + DELETE /groups/<id>/links?titles=<title>/<title>/.../<title> HTTP/1.1 + X-Hdf-domain: DOMAIN + Authorization: <authorization_string> + +.. code-block:: http + + DELETE /groups/<id>/links?separator=:&titles=<title>:<title>:...:<title> HTTP/1.1 + X-Hdf-domain: DOMAIN + Authorization: <authorization_string> + +* *<id>* is the UUID of the group containing the links to delete +* *<title>* is the url-encoded name of a requested link + +Request Parameters +------------------ + +This operation requires the parameter `titles` to specify the links to delete. Other parameters are optional. + +titles +^^^^^ +The names of the links to delete, as a single query parameter. Each individual link name is separated by a separator string. This parameter is required. + +separator +^^^^^ +The string that separates individual link names in the `titles` parameter. This parameter is optional, with a default value of `/`. + +domain +^^^^^ +The domain containing the links' parent object. This parameter is optional if the domain is specified in the request headers. + +Request Headers +--------------- +This implementation of the operation uses only the request headers that are common +to most requests. See :doc:`../CommonRequestHeaders` + +Responses +========= + +Response Headers +---------------- + +This implementation of the operation uses only response headers that are common to +most responses. See :doc:`../CommonResponseHeaders`. + +Response Elements +----------------- + +On success, an empty JSON response will be returned. + +Special Errors +-------------- + +This implementation of the operation does not return special errors. For general +information on standard error codes, see :doc:`../CommonErrorResponses`. + +Examples +======== + +Sample Request +-------------- + +.. code-block:: http + + DELETE /groups/g-45f464d8-883e-11e8-a9dc-0242ac12000e/links/?titles=lnk1/lnk2/lnk3 HTTP/1.1 + Host: hsdshdflab.hdfgroup.org + X-Hdf-domain: /shared/tall.h5 + Accept: */* + Accept-Encoding: gzip, deflate + +Sample cURL command +------------------- + +.. code-block:: bash + + $ curl -X DELETE -u username:password --header "X-Hdf-domain: /shared/tall.h5" hsdshdflab.hdfgroup.org/groups/g-45f464d8-883e-11e8-a9dc-0242ac12000e/links/?titles=lnk1/lnk2/lnk3 + +Sample Response +--------------- + +.. code-block:: http + + HTTP/1.1 200 OK + Date: Sun, 15 Jul 2018 16:06:54 GMT + Content-Length: 13 + Content-Type: application/json + Server: nginx/1.15.0 + +.. code-block:: json + + {} + +Related Resources +================= + +* :doc:`DELETE_Link` +* :doc:`GET_Links` +* :doc:`GET_Link` +* :doc:`../DatasetOps/GET_Dataset` +* :doc:`../DatatypeOps/GET_Datatype` +* :doc:`../GroupOps/GET_Group` +* :doc:`PUT_Link` + + + \ No newline at end of file diff --git a/LinkOps/GET_Link.rst b/LinkOps/GET_Link.rst new file mode 100644 index 0000000..a4887f8 --- /dev/null +++ b/LinkOps/GET_Link.rst @@ -0,0 +1,193 @@ +********************************************** +GET Link +********************************************** + +Description +=========== +Return information about a link. + +Requests +======== + +Syntax +------ + +.. code-block:: http + + GET /groups/<id>/links/<title> HTTP/1.1 + X-Hdf-domain: DOMAIN + Authorization: <authorization_string> + +.. code-block:: http + + GET /groups/<id>/links/<title>?domain=DOMAIN HTTP/1.1 + Authorization: <authorization_string> + +where: + +* *<id>* is the UUID of the group containing the link +* *<title>* is the url-encoded name of the requested link + +Request Parameters +------------------ + +domain +^^^^^ +The domain containing the link's parent object. This +parameter is optional if the domain is specified in the request headers. + +Request Headers +--------------- +This implementation of the operation uses only the request headers that are common +to most requests. See :doc:`../CommonRequestHeaders` + +Responses +========= + +Response Headers +---------------- + +This implementation of the operation uses only response headers that are common to +most responses. See :doc:`../CommonResponseHeaders`. + +Response Elements +----------------- + +On success, a JSON response will be returned containing information on the group, dataset, or committed datatype pointed to by the link. +See :doc:`../GroupOps/GET_Group`, :doc:`../DatatypeOps/GET_Datatype`, :doc:`../DatasetOps/GET_Dataset`. + +link +^^^^ +A dictionary containing information about the link. +`titles` contains the name of the link. +`class` contains the link's class - one of `H5L_TYPE_HARD`, `H5L_TYPE_SOFT`, or `H5L_TYPE_EXTERNAL`. +`id` contains the link's UUID. +`collection` contains the collection (e.g. object type) of the target object - one of `groups`, `datasets`, or `datatypes`. + +created +^^^^ +UNIX time at which the link was created. + +lastModified +^^^^ +UNIX time at which the link was last modified. + +hrefs +^^^^ +An array of links to related resources. See :doc:`../Hypermedia`. + +Special Errors +-------------- + +This implementation of the operation does not return special errors. For general +information on standard error codes, see :doc:`../CommonErrorResponses`. + +Examples +======== + +Sample Request - Get group link +-------------- + +Get the value of link named "link1" that targets a group, from a group with UUID: "g-be5996fa-...". + +.. code-block:: http + + GET /groups/g-be5996fa-83c5-11e8-a8e6-0242ac120016/links/link1 HTTP/1.1 + Host: hsdshdflab.hdfgroup.org + X-Hdf-domain: /shared/tall.h5 + Accept-Encoding: gzip, deflate + Accept: */* + +Sample cURL command - Get group link +------------------- + +.. code-block:: bash + + $ curl -X GET --header "X-Hdf-domain: /shared/tall.h5" hsdshdflab.hdfgroup.org/groups/g-be5996fa-83c5-11e8-a8e6-0242ac120016/links/link1 + +Sample Response - Get group link +--------------- + +.. code-block:: http + + HTTP/1.1 200 OK + Date: Sun, 15 Jul 2018 16:17:44 GMT + Content-Length: 522 + Etag: "55b2e2ce2d3a2449a49cfd76c4dae635ec43a150" + Content-Type: application/json + Server: nginx/1.15.0 + +.. code-block:: json + + { + 'link': { + 'title': 'link1', + 'class': 'H5L_TYPE_HARD', + 'id': 'g-ba2ffa5b-58320baa-32a7-72d3d0-ba8322', + 'collection': 'groups' + }, + 'created': 1707427765.1488154, + 'lastModified': 1707427765.1488154, + 'hrefs': + [ + {'rel': 'self', 'href': 'http://localhost:5101/groups/g-ba2ffa5b-58320baa-32a7-72d3d0-ba8322/links/link1'}, + {'rel': 'home', 'href': 'http://localhost:5101/'}, + {'rel': 'owner', 'href': 'http://localhost:5101/groups/g-ba2ffa5b-58320baa-32a7-72d3d0-ba8322'}, + {'rel': 'target', 'href': 'http://localhost:5101/groups/g-ba2ffa5b-58320baa-32a7-72d3d0-ba8322'} + ] + } + +Sample Request - Get dataset link +-------------- + +Get the value of link named "dsetlink" that targets a dataset, from a group with UUID: "g-be5996fa-...". + +.. code-block:: http + + GET /groups/g-be5996fa-83c5-11e8-a8e6-0242ac120016/links/dsetlink HTTP/1.1 + Host: hsdshdflab.hdfgroup.org + X-Hdf-domain: /shared/tall.h5 + Accept-Encoding: gzip, deflate + Accept: */* + +Sample Response - Get dataset link +--------------- + +.. code-block:: http + + HTTP/1.1 200 OK + Date: Sun, 15 Jul 2018 16:17:44 GMT + Content-Length: 522 + Etag: "55b2e2ce2d3a2449a49cfd76c4dae635ec43a150" + Content-Type: application/json + Server: nginx/1.15.0 + +.. code-block:: json + +{ + 'link': {'title': 'dsetlink', 'class': 'H5L_TYPE_HARD', 'id': 'd-52d9f0ff-f99bd504-f3f5-27f871-576bfc', 'collection': 'datasets'}, + 'created': 1707428167.7223468, + 'lastModified': 1707428167.7223468, + 'hrefs': + [ + {'rel': 'self', 'href': 'http://localhost:5101/groups/g-52d9f0ff-f99bd504-da51-787771-135d8c/links/dsetlink'}, + {'rel': 'home', 'href': 'http://localhost:5101/'}, {'rel': 'owner', 'href': 'http://localhost:5101/groups/g-52d9f0ff-f99bd504-da51-787771-135d8c'}, + {'rel': 'target', 'href': 'http://localhost:5101/datasets/d-52d9f0ff-f99bd504-f3f5-27f871-576bfc'} + ] + } + + + +Related Resources +================= + +* :doc:`DELETE_Link` +* :doc:`GET_LinkValue` +* :doc:`GET_Links` +* :doc:`../DatasetOps/GET_Dataset` +* :doc:`../DatatypeOps/GET_Datatype` +* :doc:`../GroupOps/GET_Group` +* :doc:`PUT_Link` + + + \ No newline at end of file diff --git a/LinkOps/GET_Links.rst b/LinkOps/GET_Links.rst new file mode 100644 index 0000000..0d5d09f --- /dev/null +++ b/LinkOps/GET_Links.rst @@ -0,0 +1,189 @@ +********************************************** +GET Links +********************************************** + +Description +=========== +Returns information on all the links in the target group(s). + +Requests +======== + +Syntax +------ + +.. code-block:: http + + GET /groups/<id>/links HTTP/1.1 + X-Hdf-domain: DOMAIN + Authorization: <authorization_string> + +.. code-block:: http + + GET /groups/<id>/links?domain=DOMAIN HTTP/1.1 + Authorization: <authorization_string> + +where: + +* *<id>* is the UUID of the group containing the links + +Request Parameters +------------------ + +domain +^^^^^ +The domain containing the link's parent object. This +parameter is optional if the domain is specified in the request headers. + +pattern +^^^^ +If this parameter is provided, HSDS will only return links that match this pattern according to Unix pathname pattern expansion rules. +This parameter is optional. + +Limit +^^^^ +An integer limit on the number of links that this request will return. +If not provided, HSDS will return all links. + +Marker +^^^^ +This parameter is used along with `Limit` to iterate through links in multiple requests. +This is the name of the link after which HSDS will begin returning links, in the requested order. (See 'CreateOrder') +For example, if the links `link1, link2, ... link100` exist in that order, then a request to return all links with the marker `link25` will return the set of links `link26 link27 ... link100`. + +follow_links +^^^^ +Boolean parameter specifying whether to recursively traverse groups under the target group and return links within those groups. +Default value is false. This parameter is optional. + +CreateOrder +^^^^ +Boolean parameter specifying whether the links should be returned in order of their creation. +Default value is false. This parameter is optional. +This requires the target group to track link creation order. + +Request Headers +--------------- +This implementation of the operation uses only the request headers that are common +to most requests. See :doc:`../CommonRequestHeaders` + +Responses +========= + +Response Headers +---------------- + +This implementation of the operation uses only response headers that are common to +most responses. See :doc:`../CommonResponseHeaders`. + +Response Elements +----------------- + +On success, a JSON response will be returned containing information on the group, dataset, or committed datatype pointed to by the link. +See :doc:`../GroupOps/GET_Group`, :doc:`../DatatypeOps/GET_Datatype`, :doc:`../DatasetOps/GET_Dataset`. + +links +^^^^ +A list of dictionaries containing information on each returned link. See :doc:`./GET_Link.rst` for the keys within these dicitonaries. + +Special Errors +-------------- + +This implementation of the operation does not return special errors. For general +information on standard error codes, see :doc:`../CommonErrorResponses`. + +Examples +======== + +Sample Request - Get links in group +-------------- + +Get the value all links in the group "g-aba449b2..." + +.. code-block:: http + + GET /groups/g-aba449b2-92b57d6f-232c-c13a1a-3df5e7/links HTTP/1.1 + Host: hsdshdflab.hdfgroup.org + X-Hdf-domain: /shared/tall.h5 + Accept-Encoding: gzip, deflate + Accept: */* + +Sample cURL command - Get links in group +------------------- + +.. code-block:: bash + + $ curl -X GET --header "X-Hdf-domain: /shared/tall.h5" hsdshdflab.hdfgroup.org/groups/g-aba449b2-92b57d6f-232c-c13a1a-3df5e7/links + +Sample Response - Get links in group +--------------- + +.. code-block:: http + + HTTP/1.1 200 OK + Date: Sun, 15 Jul 2018 16:17:44 GMT + Content-Length: 522 + Etag: "55b2e2ce2d3a2449a49cfd76c4dae635ec43a150" + Content-Type: application/json + Server: nginx/1.15.0 + +.. code-block:: json + + { + 'links': [ + { + 'id': 'd-aba449b2-92b57d6f-1776-8e36e6-a48cb2', + 'class': 'H5L_TYPE_HARD', + 'created': 1707491709.028682, + 'title': 'dsetlink', + 'collection': 'datasets', + 'target': 'http://localhost:5101/datasets/d-aba449b2-92b57d6f-1776-8e36e6-a48cb2', + 'href': 'http://localhost:5101/groups/g-aba449b2-92b57d6f-232c-c13a1a-3df5e7/links/dsetlink' + }, + { + 'id': 'g-aba449b2-92b57d6f-5d18-809b50-f727a7', + 'class': 'H5L_TYPE_HARD', + 'created': 1707491709.0103745, + 'title': 'g1', + 'collection': 'groups', + 'target': 'http://localhost:5101/groups/g-aba449b2-92b57d6f-5d18-809b50-f727a7', + 'href': 'http://localhost:5101/groups/g-aba449b2-92b57d6f-232c-c13a1a-3df5e7/links/g1' + }, + { + 'h5path': 'soft_link_target', + 'class': 'H5L_TYPE_SOFT', + 'created': 1707491709.0028286, + 'title': 'link2', + 'href': 'http://localhost:5101/groups/g-aba449b2-92b57d6f-232c-c13a1a-3df5e7/links/link2' + }, + ] + } + +Sample Request - Get all links in domain that start with 'dset' +-------------- + +Because the group"g-aba449b2..." is the root group, specifying recursive traversal with the `follow_links` parameter +will search over all links in the domain that follow the pattern `dset*`. + +.. code-block:: http + + GET /groups/g-00659343-38b3da69-88ed-1bcbb0-3b52e1/links?pattern=dset*&follow_links=1 HTTP/1.1 + Host: hsdshdflab.hdfgroup.org + X-Hdf-domain: /shared/tall.h5 + Accept-Encoding: gzip, deflate + Accept: */* + + +Related Resources +================= + +* :doc:`DELETE_Link` +* :doc:`GET_LinkValue` +* :doc:`GET_Links` +* :doc:`../DatasetOps/GET_Dataset` +* :doc:`../DatatypeOps/GET_Datatype` +* :doc:`../GroupOps/GET_Group` +* :doc:`PUT_Link` + + + \ No newline at end of file diff --git a/LinkOps/POST_Links.rst b/LinkOps/POST_Links.rst new file mode 100644 index 0000000..cc5d0d7 --- /dev/null +++ b/LinkOps/POST_Links.rst @@ -0,0 +1,320 @@ +********************************************** +POST Links +********************************************** + +Description +=========== +Gets information on a collection of links from the target group(s). + +Requests +======== + +Syntax +------ + +.. code-block:: http + + POST /groups/<id>/links HTTP/1.1 + X-Hdf-domain: DOMAIN + Authorization: <authorization_string> + +.. code-block:: http + + POST /groups/<id>/links?domain=DOMAIN HTTP/1.1 + Authorization: <authorization_string> + +where: + +* *<id>* is the UUID of the group searched for the provided links if `group_ids` is not provided. + +Request Parameters +------------------ +A collection of links to be read must be provided in one of three ways. + +If the same links are to be read from each target group, the links' +names should be provided in the list `titles`. + +If each target object has a unique set of links which you wish to read, then +the target link names should be provided as the value of each key within the +dictionary `grp_ids`. + +Alternatively, to return all links with titles that match a pattern, the `pattern` parameter may be provided. + +By default, the group provided in the request URL is targeted. If group ids are provdied via `grp_ids`, those group(s) will be targeted instead. + +titles +^^^^^ +A list of the titles of links which should be read from the target group(s). +This parameter is used when the same links are to be read from all target groups. + +group_ids +^^^^^ +The collection of groups to read links from. + +If the same link names are to be read from all groups, `group_ids` should be a list. + +If each target object has a different set of links which should be read from it, `group_ids` should be +a dictionary mapping each target object id to the names of the links to read from it. + +follow_links +^^^^ +Boolean parameter specifying whether to recursively traverse groups under the target group(s) while searching for links with the provided titles. +Default value is false. This parameter is optional. + +pattern +^^^^ +If this parameter is provided, HSDS will only return links that match this pattern according to Unix pathname pattern expansion rules. +This parameter is optional. + +domain +^^^^^ +The domain containing the links to retrieve. This +parameter is optional if the domain is specified in the request headers. + + +Request Headers +--------------- +This implementation of the operation uses only the request headers that are common +to most requests. See :doc:`../CommonRequestHeaders` + +Responses +========= + +Response Headers +---------------- + +This implementation of the operation uses only response headers that are common to +most responses. See :doc:`../CommonResponseHeaders`. + +Response Elements +----------------- + +On success, a JSON response will be returned with the following elements: + + +links +^^^^^^^^^^ +If a single group is targeted, this is a list of objects which each describe a link. +If more than one group is targeted or searched, this is an object mapping every searched group id +to each group's returned link objects. A group id may be mapped to an empty object if no links were found under that group. + +See :doc:`GET_Link` for a description of the individual link objects. + +Special Errors +-------------- + +This implementation of the operation does not return special errors. For general +information on standard error codes, see :doc:`../CommonErrorResponses`. + +Examples +======== + +Sample Request +-------------- + +Get the link named "link1" and "link2" from the group "g-63ea97d5..." + +.. code-block:: http + + POST /groups/g-63ea97d5-5ed538a7-eb62-1f5dd6-5db02f/links HTTP/1.1 + Host: hsdshdflab.hdfgroup.org + X-Hdf-domain: /shared/tall.h5 + Accept-Encoding: gzip, deflate + Accept: */* + +.. code-block:: json + { + "titles": + [ + "link1", + "link2" + ] + } + +Sample Response +--------------- + +.. code-block:: http + + HTTP/1.1 200 OK + Date: Sun, 15 Jul 2018 16:23:43 GMT + Content-Length: 797 + Etag: "7cbeefcf8d9997a8865bdea3bf2d541a14e9bf71" + Content-Type: application/json + Server: nginx/1.15.0 + +.. code-block:: json + + { + 'links': [ + { + 'class': 'H5L_TYPE_HARD', + 'created': 1707496239.3933172, + 'id': 'g-63ea97d5-5ed538a7-eb62-1f5dd6-5db02f', + 'title': 'link1' + }, + { + 'class': 'H5L_TYPE_SOFT', + 'created': 1707497727.0149524, + 'h5path': 'soft_link_target', + 'title': 'link2' + } + ] + } + +Sample Request - Read same link title from multiple groups +--------------------------- + +.. code-block:: http + + POST /groups/g-45f464d8-883e-11e8-a9dc-0242ac12000e/links HTTP/1.1 + Host: hsdshdflab.hdfgroup.org + X-Hdf-domain: /shared/tall.h5 + Accept-Encoding: gzip, deflate + Accept: */* + +.. code-block:: json + + { + "titles": + [ + "link1" + ], + "grp_ids": + [ + "g-83a603fe-5e32fffe-0b2e-8b76d6-ba7776", + "g-83a603fe-5e32fffe-19a6-d55996-9adb95" + ] + } + +Sample Response - Read same link from multiple groups +--------------------------- + +.. code-block:: http + + HTTP/1.1 200 OK + Date: Sun, 15 Jul 2018 16:38:16 GMT + Content-Length: 1767 + Etag: "9483f4356e08d12b719aa64ece09e659b05adaf2" + Content-Type: application/json + Server: nginx/1.15.0 + +.. code-block:: json + + { + 'links': { + 'g-a0ff86b8-a4759af1-2877-0e302c-fd1279': [ + {'id': 'g-a0ff86b8-a4759af1-2877-0e302c-fd1279', 'class': 'H5L_TYPE_HARD', 'created': 1708100156.1945097, 'title': 'link1'} + ], + 'g-a0ff86b8-a4759af1-18b6-fd1c34-2f30c2': [ + {'id': 'g-a0ff86b8-a4759af1-2877-0e302c-fd1279', 'class': 'H5L_TYPE_HARD', 'created': 1708100156.2084465, 'title': 'link1'} + ] + } + } + +Sample Request - Search for link in all subgroups +--------------------------- + +In this example, `link2` exists in a subgroup, and the request is sent to the root group with the `follow_links` parameter enabled to search all subgroups. + +.. code-block:: http + + POST /groups/g-45f464d8-883e-11e8-a9dc-0242ac12000e/links?follow_links=1 HTTP/1.1 + Host: hsdshdflab.hdfgroup.org + X-Hdf-domain: /shared/tall.h5 + Accept-Encoding: gzip, deflate + Accept: */* + +.. code-block:: json + + { + "titles": + [ + "link2" + ], + } + +Sample Response - Search for link in all subgroups +--------------------------- + +.. code-block:: http + + HTTP/1.1 200 OK + Date: Sun, 15 Jul 2018 16:38:16 GMT + Content-Length: 1767 + Etag: "9483f4356e08d12b719aa64ece09e659b05adaf2" + Content-Type: application/json + Server: nginx/1.15.0 + +.. code-block:: json + + { + 'links': { + 'g-6c472826-634d6313-e4cf-a0aeeb-c5eb9b': [ + {'h5path': 'soft_link_target', 'class': 'H5L_TYPE_SOFT', 'created': 1708101851.0649424, 'title': 'link2'} + ], + 'g-6c472826-634d6313-9c71-ea8f30-337e96': [] + } + } + +Sample Request - Search for name pattern in all subgroups +--------------------------- + +This examples searches all groups recursively from the group with id `g-...3511.` and returns all links with titles that match the pattern `*1`. +Note that in this case, the group used in the request URL is ignored. + +.. code-block:: http + + POST /groups/g-45f464d8-883e-11e8-a9dc-0242ac12000e/links?follow_links=1&pattern=*1 HTTP/1.1 + Host: hsdshdflab.hdfgroup.org + X-Hdf-domain: /shared/tall.h5 + Accept-Encoding: gzip, deflate + Accept: */* + +.. code-block:: json + + { + "grp_ids": [ + "g-791e9ee1-692bbd99-f196-1669e1-a33511" + ] + } + +Sample Response - Search for link in all subgroups +--------------------------- + +.. code-block:: http + + HTTP/1.1 200 OK + Date: Sun, 15 Jul 2018 16:38:16 GMT + Content-Length: 1767 + Etag: "9483f4356e08d12b719aa64ece09e659b05adaf2" + Content-Type: application/json + Server: nginx/1.15.0 + +.. code-block:: json + + { + 'links': { + 'g-791e9ee1-692bbd99-f196-1669e1-a33511': [ + {'id': 'g-791e9ee1-692bbd99-ceb3-4d4bdd-93e70b', 'class': 'H5L_TYPE_HARD', 'created': 1708102965.0489032, 'title': 'g1'}, + {'id': 'g-791e9ee1-692bbd99-f196-1669e1-a33511', 'class': 'H5L_TYPE_HARD', 'created': 1708102965.0385375, 'title': 'link1'} + ], + 'g-791e9ee1-692bbd99-ceb3-4d4bdd-93e70b': [ + {'id': 'g-791e9ee1-692bbd99-f196-1669e1-a33511', 'class': 'H5L_TYPE_HARD', 'created': 1708102965.0537355, 'title': 'link1'} + ] + } + } + + + +Related Resources +================= + +* :doc:`DELETE_Link` +* :doc:`POST_Links` +* :doc:`../DatasetOps/POST_Dataset` +* :doc:`../DatatypeOps/POST_Datatype` +* :doc:`../GroupOps/POST_Group` +* :doc:`PUT_Link` + + diff --git a/LinkOps/PUT_Link.rst b/LinkOps/PUT_Link.rst new file mode 100644 index 0000000..e75ce9f --- /dev/null +++ b/LinkOps/PUT_Link.rst @@ -0,0 +1,136 @@ +********************************************** +PUT Link +********************************************** + +Description +=========== +Creates a new link to a group, dataset, or committed datatype. +Attempting to create a link to an object that does not exist will fail for a hard link, but succeed for soft and external links. + +*Note*: The link creation will fail if a link with the same name in the same location already exists. + +Requests +======== + +Syntax +------ + +To create a group link: + +.. code-block:: http + + PUT /groups/<id>/links/<title> HTTP/1.1 + X-Hdf-domain: DOMAIN + Authorization: <authorization_string> + +.. code-block:: http + + PUT /groups/<id>/links/<title>?domain=DOMAIN HTTP/1.1 + Authorization: <authorization_string> + +* *<id>* is the UUID of the group that will contain the new link +* *<title>* is the url-encoded name of the requested link + +Request Parameters +------------------ + +domain +^^^^^ +The domain containing the link's parent object. This +parameter is optional if the domain is specified in the request headers. + +Request Headers +--------------- +This implementation of the operation uses only the request headers that are common +to most requests. See :doc:`../CommonRequestHeaders` + +Request Elements +---------------- + +id +^^^^ +The UUID of the object that the new link will point to. This should only be provided for hard links. + +h5path +^^^^ +The path to the object the new link will point to. This should be provided for soft and external links. + +h5domain +^^^^ +The domain containing the object the new link will point to. This should be provided only for external links. + +Responses +========= + +Response Headers +---------------- + +This implementation of the operation uses only response headers that are common to +most responses. See :doc:`../CommonResponseHeaders`. + +Response Elements +----------------- + +On success, a JSON response will be returned with the following elements: + +hrefs +^^^^^ +An empty array. See :doc:`../Hypermedia`. + +Special Errors +-------------- + +This implementation of the operation does not return special errors. For general +information on standard error codes, see :doc:`../CommonErrorResponses`. + +Examples +======== + +Sample Request - Hard Link +---------------------------------- + +This request creates a hard link called "hardlnk" to the root group. The created link itself resides within the root group. + +.. code-block:: http + + PUT /groups/g-51db5cdf-08b64144-d953-d45780-3ec9cc/links/hardlnk HTTP/1.1 + Host: hsdshdflab.hdfgroup.org + X-Hdf-domain: /shared/tall.h5 + Content-Length: 38 + Accept: */* + Accept-Encoding: gzip, deflate + + +.. code-block:: json + + { + "id": "g-51db5cdf-08b64144-d953-d45780-3ec9cc" + } + +Sample Response - Hard Link +----------------------------------- + +.. code-block:: http + + HTTP/1.1 201 Created + Date: Sun, 15 Jul 2018 15:07:03 GMT + Content-Length: 13 + Content-Type: application/json + Server: nginx/1.15.0 + +.. code-block:: json + + {"hrefs": []} + +Related Resources +================= + +* :doc:`DELETE_Link` +* :doc:`GET_Link` +* :doc:`GET_Links` +* :doc:`../DatasetOps/GET_Dataset` +* :doc:`../DatatypeOps/GET_Datatype` +* :doc:`../GroupOps/GET_Group` + + + diff --git a/LinkOps/PUT_Links.rst b/LinkOps/PUT_Links.rst new file mode 100644 index 0000000..0a42a12 --- /dev/null +++ b/LinkOps/PUT_Links.rst @@ -0,0 +1,194 @@ +********************************************** +PUT Links +********************************************** + +Description +=========== +Creates new links to groups, datasets, or committed datatypes. +Attempting to create a link to an object that does not exist will fail for a hard link, but succeed for soft and external links. + +*Note*: The link creation will fail if a link with the same name in the same location already exists. + +Requests +======== + +Syntax +------ + +To create a group link: + +.. code-block:: http + + PUT /groups/<id>/links HTTP/1.1 + X-Hdf-domain: DOMAIN + Authorization: <authorization_string> + +.. code-block:: http + + PUT /groups/<id>/links?domain=DOMAIN HTTP/1.1 + Authorization: <authorization_string> + +* *<id>* is the UUID of the group that will contain the new links by default + +Request Parameters +------------------ + +domain +^^^^^ +The domain containing the link's parent object. This +parameter is optional if the domain is specified in the request headers. + +Request Headers +--------------- +This implementation of the operation uses only the request headers that are common +to most requests. See :doc:`../CommonRequestHeaders` + +Request Elements +---------------- + +This request requires exactly one of `links` or `grp_ids` (as a dictionary) to be provided. + +links +^^^^ +A dictionary of links to create. +The keys are the link titles, and the bodies are the information describing the link to create (See "Request Elements" in :docs:`./Put_Link.rst`). + +grp_ids +^^^^ +A set of group UUIDs for groups that will contain the newly created links. May be a list or a dictionary. +If it is a list, each link provided in 'links' will be written to each of these groups. +If it is a dictionary, it should map each group UUID to a dictionary whose `links` key contains a dictionary mapping each link title to its information. +If it is not provided, each link will be stored in the group from the request URL. + +Responses +========= + +Response Headers +---------------- + +This implementation of the operation uses only response headers that are common to +most responses. See :doc:`../CommonResponseHeaders`. + +Response Elements +----------------- + +On success, an empty JSON response will be returned. + +Special Errors +-------------- + +This implementation of the operation does not return special errors. For general +information on standard error codes, see :doc:`../CommonErrorResponses`. + +Examples +======== + +Sample Request - Links in a single group +---------------------------------- + +This request creates a hard link called "hardlnk" to the root group. The created link itself resides within the root group. + +.. code-block:: http + + PUT /groups/g-51db5cdf-08b64144-d953-d45780-3ec9cc/links HTTP/1.1 + Host: hsdshdflab.hdfgroup.org + X-Hdf-domain: /shared/tall.h5 + Content-Length: 38 + Accept: */* + Accept-Encoding: gzip, deflate + + +.. code-block:: json + + { + "links": { + "link1": {"id": "g-51db5cdf-08b64144-d953-d45780-3ec9cc"}, + "link2":{"h5path": "soft_link_target"} + } + } + +Sample Response - Links in a single group +----------------------------------- + +.. code-block:: http + + HTTP/1.1 201 Created + Date: Sun, 15 Jul 2018 15:07:03 GMT + Content-Length: 13 + Content-Type: application/json + Server: nginx/1.15.0 + +.. code-block:: json + + {} + +Sample Request - Create all links in each target group +---------------------------------- + +.. code-block:: http + + PUT /groups/g-51db5cdf-08b64144-d953-d45780-3ec9cc/links HTTP/1.1 + Host: hsdshdflab.hdfgroup.org + X-Hdf-domain: /shared/tall.h5 + Content-Length: 38 + Accept: */* + Accept-Encoding: gzip, deflate + + +.. code-block:: json + + { + "grp_ids": + [ + "g-5c8d8f09-4609b340-d405-0781ce-813bc8", + "g-5c8d8f09-4609b340-716d-e1bd7f-c77cbe" + ], + "links": + { + "link3":{"id": "g-51db5cdf-08b64144-d953-d45780-3ec9cc"}, + "link4": {"h5path": "soft_link_target"} + } + } + +Sample Request - Create different link(s) in each target group +---------------------------------- + +.. code-block:: http + + PUT /groups/g-51db5cdf-08b64144-d953-d45780-3ec9cc/links HTTP/1.1 + Host: hsdshdflab.hdfgroup.org + X-Hdf-domain: /shared/tall.h5 + Content-Length: 38 + Accept: */* + Accept-Encoding: gzip, deflate + + +.. code-block:: json + { + "grp_ids": + { + "g-53cb7319-e27507cf-db43-fb916a-fd8f47": + { + "links": {"link5":{"id": "g-53cb7319-e27507cf-db43-fb916a-fd8f47"}} + }, + + "g-53cb7319-e27507cf-0749-7ba6b7-af764d": + { + "links": {"link6": {"h5path": "soft_link_target"}} + } + } + } + + +Related Resources +================= + +* :doc:`DELETE_Link` +* :doc:`GET_Link` +* :doc:`GET_Links` +* :doc:`../DatasetOps/GET_Dataset` +* :doc:`../DatatypeOps/GET_Datatype` +* :doc:`../GroupOps/GET_Group` + + +