Skip to content

Commit

Permalink
more doc updates
Browse files Browse the repository at this point in the history
  • Loading branch information
@jreadey
jreadey committed Feb 3, 2015
1 parent 549a422 commit db3fee0
Show file tree
Hide file tree
Showing 4 changed files with 197 additions and 41 deletions.
66 changes: 65 additions & 1 deletion docs/DatasetOps/GET_Value.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,22 @@ Syntax

Request Parameters
------------------
This implementation of the operation does not use request parameters.

select
^^^^^^
Optionally the request can provide a select value to indicate a hyperslab selection for
the values to be returned - i.e. a rectangular (in 1, 2, or more dimensions) region of
the dataset. Format is the following as a url-encoded value:

[dim1_start:dim1_end:dim1_step, dim2_start:dim2_end:dim2_step, ... , dimn_start:dimn_stop:dimn_step]

The number of tuples "start:stop:step" should equal the number of dimensions of the dataset.

For each tuple:

* start must be greater than equal to zero and less than the dimension extent
* stop must be greater than or equal to start and less than the dimension extent
* step is optional and if provided must be greater than 0. If not provided, the step value for that dimension is assumed to be 1.

Request Headers
---------------
Expand All @@ -42,6 +57,11 @@ Response Elements

On success, a JSON response will be returned with the following elements:

value
^^^^^
A json array (or value for scalar datasets) giving the values of the requested
dataset region.

hrefs
^^^^^
An array of links to related resources. See :doc:`../Hypermedia`.
Expand Down Expand Up @@ -102,6 +122,50 @@ Sample Response
]
}
Sample Request - Selection
--------------------------

.. code-block:: http
GET /datasets/a299db70-ab57-11e4-9c00-3c15c2da029e/value?select=[1:9,1:9:2] HTTP/1.1
host: tall.test.hdfgroup.org
Accept-Encoding: gzip, deflate
Accept: */*
User-Agent: python-requests/2.3.0 CPython/2.7.8 Darwin/14.0.0
Sample Response - Selection
---------------------------

.. code-block:: http
HTTP/1.1 200 OK
Date: Tue, 03 Feb 2015 04:01:41 GMT
Content-Length: 529
Etag: "b370a3d34bdd7ebf57a496bc7f0da7bc5a1aafb9"
Content-Type: application/json
Server: TornadoServer/3.2.2
.. code-block:: json
{
"value": [
[1, 3, 5, 7],
[2, 6, 10, 14],
[3, 9, 15, 21],
[4, 12, 20, 28],
[5, 15, 25, 35],
[6, 18, 30, 42],
[7, 21, 35, 49],
[8, 24, 40, 56]
],
"hrefs": [
{"href": "http://tall.test.hdfgroup.org/datasets/a299db70-ab57-11e4-9c00-3c15c2da029e/value", "rel": "self"},
{"href": "http://tall.test.hdfgroup.org/groups/a29982cf-ab57-11e4-b976-3c15c2da029e", "rel": "root"},
{"href": "http://tall.test.hdfgroup.org/datasets/a299db70-ab57-11e4-9c00-3c15c2da029e", "rel": "owner"},
{"href": "http://tall.test.hdfgroup.org/", "rel": "home"}
]
}
Related Resources
=================

Expand Down
45 changes: 29 additions & 16 deletions docs/DatasetOps/POST_Value.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,8 @@ POST Value

Description
===========
Gets values of a data for a given point selection.
Gets values of a data for a given point selection (provided in the body of the
request).

Requests
========
Expand All @@ -13,7 +14,7 @@ Syntax
------
.. code-block:: http
DELETE /groups/<id> HTTP/1.1
POST /datasets/<id>/value HTTP/1.1
Host: DOMAIN
Authorization: <authorization_string>
Expand All @@ -28,6 +29,18 @@ Request Headers
This implementation of the operation uses only the request headers that are common
to most requests. See :doc:`../CommonRequestHeaders`

Request Body
------------

The request body should be a JSON object with the following key:

points
^^^^^^

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.

Responses
=========

Expand All @@ -42,9 +55,11 @@ Response Elements

On success, a JSON response will be returned with the following elements:

hrefs
value
^^^^^
An array of links to related resources. See :doc:`../Hypermedia`.
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 consist
with the dataset type (e.g. an compound type).

Special Errors
--------------
Expand All @@ -60,30 +75,28 @@ Sample Request

.. code-block:: http
DELETE /groups/45a882e1-9d01-11e4-8acf-3c15c2da029e HTTP/1.1
Host: testGroupDelete.test.hdfgroup.org
Authorization: authorization_string
POST /datasets/4e83ad1c-ab6e-11e4-babb-3c15c2da029e/value HTTP/1.1
Content-Length: 92
User-Agent: python-requests/2.3.0 CPython/2.7.8 Darwin/14.0.0
host: tall.test.hdfgroup.org
Accept: */*
Accept-Encoding: gzip, deflate
Sample Response
---------------

.. code-block:: http
HTTP/1.1 200 OK
Date: Thu, 15 Jan 2015 21:55:51 GMT
Content-Length: 270
Date: Tue, 03 Feb 2015 06:31:38 GMT
Content-Length: 47
Content-Type: application/json
Server: TornadoServer/3.2.2
.. code-block:: json
{
"hrefs": [
{"href": "http://testGroupDelete.test.hdfgroup.org/groups", "rel": "self"},
{"href": "http://testGroupDelete.test.hdfgroup.org/groups/45a06719-9d01-11e4-9b1c-3c15c2da029e", "rel": "root"},
{"href": "http://testGroupDelete.test.hdfgroup.org/", "rel": "home"}
]
"value": [0, 1, 4, 9, 16, 25, 36, 49, 64, 81]
}
Related Resources
Expand Down
118 changes: 98 additions & 20 deletions docs/DatasetOps/PUT_Value.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ PUT Value

Description
===========
Update the Values in a dataset.
Update the values in a dataset.

Requests
========
Expand All @@ -13,7 +13,7 @@ Syntax
------
.. code-block:: http
DELETE /groups/<id> HTTP/1.1
PUT /datasets/<id> HTTP/1.1
Host: DOMAIN
Authorization: <authorization_string>
Expand All @@ -28,6 +28,40 @@ Request Headers
This implementation of the operation uses only the request headers that are common
to most requests. See :doc:`../CommonRequestHeaders`

Request Body
------------
The request body should be a JSON object with the following keys:

start:
^^^^^^
An optional key that gives the starting coordinate of the selection to be updated. The
start value can either be an integer (for 1 dimensional arrays) or an array of integers
where the length of the array is equal to the number of dimensions of the dataset. Each
value must be greater than equal to zero and less than the extent of the corresponding
dimension.

If start is not provided, the selection starts at 0 for each dimension.

stop:
^^^^^
An optional key that gives the ending coordinate of the selection to be updated.
The stop value can either be an integer (for 1 dimensional arrays) or an array of integers
where the length of the array is equal to the number of dimensions of the dataset. Each
value must be greater than equal to start (or zero if start is not provided) and less than
the extent of the corresponding dimension.

step:
^^^^^
An optional key that gives the step value (i.e. the increment of the coordinate for
each supplied value). The step value can either be an integer (for 1 dimensional arrays) or
an array of integers where the length of the array is equal to the number of dimensions of
the dataset. Each value must be greater than equal to start (or zero if start is not
provided) and less than the extent of the corresponding dimension.

value:
^^^^^^
A JSON array containing the data values to be written.

Responses
=========

Expand All @@ -40,11 +74,7 @@ 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`.
No response elements are returned.

Special Errors
--------------
Expand All @@ -55,37 +85,85 @@ information on standard error codes, see :doc:`../CommonErrorResponses`.
Examples
========


Sample Request
--------------

This example writes a 10x10 integer datasets with the values 0-99 inclusive.

.. code-block:: http
DELETE /groups/45a882e1-9d01-11e4-8acf-3c15c2da029e HTTP/1.1
Host: testGroupDelete.test.hdfgroup.org
Authorization: authorization_string
PUT /datasets/817e2280-ab5d-11e4-afe6-3c15c2da029e/value HTTP/1.1
Content-Length: 465
User-Agent: python-requests/2.3.0 CPython/2.7.8 Darwin/14.0.0
host: valueput.datasettest.test.hdfgroup.org
Accept: */*
Accept-Encoding: gzip, deflate
.. code-block:: json
{
"value": [
[0, 1, 2, 3, 4, 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],
[30, 31, 32, 33, 34, 35, 36, 37, 38, 39],
[40, 41, 42, 43, 44, 45, 46, 47, 48, 49],
[50, 51, 52, 53, 54, 55, 56, 57, 58, 59],
[60, 61, 62, 63, 64, 65, 66, 67, 68, 69],
[70, 71, 72, 73, 74, 75, 76, 77, 78, 79],
[80, 81, 82, 83, 84, 85, 86, 87, 88, 89],
[90, 91, 92, 93, 94, 95, 96, 97, 98, 99]
]
}
Sample Response
---------------

.. code-block:: http
HTTP/1.1 200 OK
Date: Thu, 15 Jan 2015 21:55:51 GMT
Content-Length: 270
Content-Type: application/json
Date: Tue, 03 Feb 2015 04:31:22 GMT
Content-Length: 0
Content-Type: text/html; charset=UTF-8
Server: TornadoServer/3.2.2
.. code-block:: json
Sample Request - Selection
--------------------------

This example writes a portion of the dataset by using the start and stop keys in the
request.

.. code-block:: http
PUT /datasets/b2d0af00-ab65-11e4-a874-3c15c2da029e/value HTTP/1.1
Content-Length: 92
User-Agent: python-requests/2.3.0 CPython/2.7.8 Darwin/14.0.0
host: valueputsel.datasettest.test.hdfgroup.org
Accept: */*
Accept-Encoding: gzip, deflate
{
"hrefs": [
{"href": "http://testGroupDelete.test.hdfgroup.org/groups", "rel": "self"},
{"href": "http://testGroupDelete.test.hdfgroup.org/groups/45a06719-9d01-11e4-9b1c-3c15c2da029e", "rel": "root"},
{"href": "http://testGroupDelete.test.hdfgroup.org/", "rel": "home"}
]
.. code-block:: json
{
"start": 5,
"stop": 10,
"value": [13, 17, 19, 23, 29]
}
Sample Response
---------------

.. code-block:: http
HTTP/1.1 200 OK
Date: Tue, 03 Feb 2015 05:30:01 GMT
Content-Length: 0
Content-Type: text/html; charset=UTF-8
Server: TornadoServer/3.2.2
Related Resources
=================

Expand Down
9 changes: 5 additions & 4 deletions test/integ/valuetest.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -510,7 +510,8 @@ def testPut(self):

req = self.endpoint + "/datasets/" + dset1UUID + "/value"
data = [2,3,5,7,11,13,17,19,23,29]
payload = {'type': 'H5T_STD_I32LE', 'shape': 10, 'value': data }
# payload = {'type': 'H5T_STD_I32LE', 'shape': 10, 'value': data }
payload = { 'value': data }
headers = {'host': domain}
rsp = requests.put(req, data=json.dumps(payload), headers=headers)
self.failUnlessEqual(rsp.status_code, 200)
Expand Down Expand Up @@ -538,7 +539,7 @@ def testPut(self):
for j in range(10):
row.append(i*10 + j)
data.append(row)
payload = {'type': 'H5T_STD_I32LE', 'shape': [10, 10], 'value': data }
payload = { 'value': data }
headers = {'host': domain}
rsp = requests.put(req, data=json.dumps(payload), headers=headers)
self.failUnlessEqual(rsp.status_code, 200)
Expand Down Expand Up @@ -572,12 +573,12 @@ def testPutSelection(self):
data_part1 = data[0:5]
data_part2 = data[5:10]
# write part 1
payload = {'type': 'H5T_STD_I32LE', 'shape': 5, 'start': 0, 'stop': 5, 'value': data_part1 }
payload = { 'start': 0, 'stop': 5, 'value': data_part1 }
headers = {'host': domain}
rsp = requests.put(req, data=json.dumps(payload), headers=headers)
self.failUnlessEqual(rsp.status_code, 200)
# write part 2
payload = {'type': 'H5T_STD_I32LE', 'shape': 5, 'start': 5, 'stop': 10, 'value': data_part2 }
payload = { 'start': 5, 'stop': 10, 'value': data_part2 }
headers = {'host': domain}
rsp = requests.put(req, data=json.dumps(payload), headers=headers)
self.failUnlessEqual(rsp.status_code, 200)
Expand Down

0 comments on commit db3fee0

Please sign in to comment.