Introduction
See Service API Design for the rationale and design details for this api.
See Developer Bootstrap#DeveloperBootstrap-ServiceDevelopment for instructions on how to run a local instance of this service.
Encoding
The primary request and response encoding for the service is JSON. Here's a handy tool to make a blob of JSON more readable: http://jsonformatter.curiousconcept.com/
In responses from the service, dates are serialized as long integers expressing epoch time - the number of seconds elapsed since midnight Coordinated Universal Time (UTC) of January 1, 1970, not counting leap seconds. Here's a handy tool to convert from epoch time to human readable dates: http://www.epochconverter.com/
In requests to the service, dates can be serialized either as long integers expressing epoch time or human readable dates in [http://www.ietf.org/rfc/rfc3339.txt ] format such as '2011-01-31' or '2011-01-31T22:00:00'
Security
Eventually these services will be HTTPS only and disallow HTTP. Users will pass something like ?access_token=... as a query parameter for every request to the service
Usage Examples
This is a REST api (see Service API Design for more details as to what this means). You can create entities, updated entities, read entities, and delete entities. More advanced querying will be implemented as a separate API. Partial updates (e.g., just updating two fields in a dataset) are not supported. In a nutshell, when you update something like a dataset, you GET the dataset first, modify the properties you want to change, and then send the entire object back to the service so that this revised entity overwrites the previously stored entity.
Get Datasets
Optional Parameters
- offset - integer - 1-based pagination offset
- limit - integer - maximum number of results to return
- sort - string - the name of the primary field upon which to sort
- ascending - boolean - whether or not to sort ascending
Request
curl -i -H Accept:application/json "http://deflaux-test.appspot.com/repo/v1/dataset?limit=3"
Response
HTTP/1.1 200 OK
ETag: 22610276
Content-Type: application/json
Date: Tue, 01 Feb 2011 18:07:45 GMT
Server: Google Frontend
Cache-Control: private, x-gzip-ok=""
Transfer-Encoding: chunked
{
"results":[
{
"name":"Pediatric AML TARGET",
"annotations":"/repo/v1/dataset/agxkZWZsYXV4LXRlc3RyFQsSDUdBRUpET0RhdGFzZXQYgvcCDA/annotations",
"id":"agxkZWZsYXV4LXRlc3RyFQsSDUdBRUpET0RhdGFzZXQYgvcCDA",
"version":"0.0.1",
"description":null,
"status":"In Transition",
"uri":"/repo/v1/dataset/agxkZWZsYXV4LXRlc3RyFQsSDUdBRUpET0RhdGFzZXQYgvcCDA",
"etag":"1703131409",
"creator":"Soheil Meshinchi",
"creationDate":1296182253120,
"releaseDate":null,
"layers":[
{
"id":"agxkZWZsYXV4LXRlc3RyEwsSDUdBRUpET0RhdGFzZXQYAQw",
"type":"C",
"uri":"/datalayer/agxkZWZsYXV4LXRlc3RyEwsSDUdBRUpET0RhdGFzZXQYAQw"
},
{
"id":"agxkZWZsYXV4LXRlc3RyFQsSDUdBRUpET0RhdGFzZXQYiaECDA",
"type":"E",
"uri":"agxkZWZsYXV4LXRlc3RyFQsSDUdBRUpET0RhdGFzZXQYiaECDA"
},
{
"id":"agxkZWZsYXV4LXRlc3RyFQsSDUdBRUpET0RhdGFzZXQYmfIBDA",
"type":"G",
"uri":"/datalayer/agxkZWZsYXV4LXRlc3RyFQsSDUdBRUpET0RhdGFzZXQYmfIBDA"
}
]
},
{
"name":"Flint HS Mice",
"annotations":"/repo/v1/dataset/agxkZWZsYXV4LXRlc3RyFQsSDUdBRUpET0RhdGFzZXQY2q0DDA/annotations",
"id":"agxkZWZsYXV4LXRlc3RyFQsSDUdBRUpET0RhdGFzZXQY2q0DDA",
"version":"0.0.1",
"description":null,
"status":"Future",
"uri":"/repo/v1/dataset/agxkZWZsYXV4LXRlc3RyFQsSDUdBRUpET0RhdGFzZXQY2q0DDA",
"etag":"1025901212",
"creator":"Jonathan Flint",
"creationDate":1296182255070,
"releaseDate":null,
"layers":[
{
"id":"agxkZWZsYXV4LXRlc3RyEwsSDUdBRUpET0RhdGFzZXQYAQw",
"type":"C",
"uri":"/datalayer/agxkZWZsYXV4LXRlc3RyEwsSDUdBRUpET0RhdGFzZXQYAQw"
},
{
"id":"agxkZWZsYXV4LXRlc3RyFQsSDUdBRUpET0RhdGFzZXQYiaECDA",
"type":"E",
"uri":"agxkZWZsYXV4LXRlc3RyFQsSDUdBRUpET0RhdGFzZXQYiaECDA"
},
{
"id":"agxkZWZsYXV4LXRlc3RyFQsSDUdBRUpET0RhdGFzZXQYmfIBDA",
"type":"G",
"uri":"/datalayer/agxkZWZsYXV4LXRlc3RyFQsSDUdBRUpET0RhdGFzZXQYmfIBDA"
}
]
},
{
"name":"Glioblastoma TCGA",
"annotations":"/repo/v1/dataset/agxkZWZsYXV4LXRlc3RyFQsSDUdBRUpET0RhdGFzZXQYseQDDA/annotations",
"id":"agxkZWZsYXV4LXRlc3RyFQsSDUdBRUpET0RhdGFzZXQYseQDDA",
"version":"0.0.1",
"description":null,
"status":"Available",
"uri":"/repo/v1/dataset/agxkZWZsYXV4LXRlc3RyFQsSDUdBRUpET0RhdGFzZXQYseQDDA",
"etag":"456728335",
"creator":null,
"creationDate":1296182238229,
"releaseDate":null,
"layers":[
{
"id":"agxkZWZsYXV4LXRlc3RyEwsSDUdBRUpET0RhdGFzZXQYAQw",
"type":"C",
"uri":"/datalayer/agxkZWZsYXV4LXRlc3RyEwsSDUdBRUpET0RhdGFzZXQYAQw"
},
{
"id":"agxkZWZsYXV4LXRlc3RyFQsSDUdBRUpET0RhdGFzZXQYiaECDA",
"type":"E",
"uri":"agxkZWZsYXV4LXRlc3RyFQsSDUdBRUpET0RhdGFzZXQYiaECDA"
},
{
"id":"agxkZWZsYXV4LXRlc3RyFQsSDUdBRUpET0RhdGFzZXQYmfIBDA",
"type":"G",
"uri":"/datalayer/agxkZWZsYXV4LXRlc3RyFQsSDUdBRUpET0RhdGFzZXQYmfIBDA"
}
]
}
],
"totalNumberOfResults":10,
"paging":{
"next":"/repo/v1/dataset?offset=4&limit=3"
}
}
Get a Dataset
Request
curl -i -H Accept:application/json "http://deflaux-test.appspot.com/repo/v1/dataset/agxkZWZsYXV4LXRlc3RyFQsSDUdBRUpET0RhdGFzZXQYseQDDA"
Response
HTTP/1.1 200 OK
ETag: 456728335
Content-Type: application/json
Date: Tue, 01 Feb 2011 18:22:24 GMT
Server: Google Frontend
Cache-Control: private, x-gzip-ok=""
Transfer-Encoding: chunked
{
"name":"Glioblastoma TCGA",
"annotations":"/repo/v1/dataset/agxkZWZsYXV4LXRlc3RyFQsSDUdBRUpET0RhdGFzZXQYseQDDA/annotations",
"id":"agxkZWZsYXV4LXRlc3RyFQsSDUdBRUpET0RhdGFzZXQYseQDDA",
"version":"0.0.1",
"description":null,
"status":"Available",
"uri":"/repo/v1/dataset/agxkZWZsYXV4LXRlc3RyFQsSDUdBRUpET0RhdGFzZXQYseQDDA",
"etag":"456728335",
"creator":null,
"creationDate":1296182238229,
"releaseDate":null,
"layers":[
{
"id":"agxkZWZsYXV4LXRlc3RyEwsSDUdBRUpET0RhdGFzZXQYAQw",
"type":"C",
"uri":"/datalayer/agxkZWZsYXV4LXRlc3RyEwsSDUdBRUpET0RhdGFzZXQYAQw"
},
{
"id":"agxkZWZsYXV4LXRlc3RyFQsSDUdBRUpET0RhdGFzZXQYiaECDA",
"type":"E",
"uri":"agxkZWZsYXV4LXRlc3RyFQsSDUdBRUpET0RhdGFzZXQYiaECDA"
},
{
"id":"agxkZWZsYXV4LXRlc3RyFQsSDUdBRUpET0RhdGFzZXQYmfIBDA",
"type":"G",
"uri":"/datalayer/agxkZWZsYXV4LXRlc3RyFQsSDUdBRUpET0RhdGFzZXQYmfIBDA"
}
]
}
Get Annotations for a Dataset
Request
curl -i -H Accept:application/json "http://deflaux-test.appspot.com/repo/v1/dataset/agxkZWZsYXV4LXRlc3RyFQsSDUdBRUpET0RhdGFzZXQYseQDDA/annotations"
Response
HTTP/1.1 200 OK
ETag: -1919132670
Content-Type: application/json
Date: Tue, 01 Feb 2011 18:24:15 GMT
Server: Google Frontend
Cache-Control: private, x-gzip-ok=""
Transfer-Encoding: chunked
{
"id":"agxkZWZsYXV4LXRlc3RyFQsSDUdBRUpET0RhdGFzZXQYseQDDA",
"uri":"/repo/v1/dataset/agxkZWZsYXV4LXRlc3RyFQsSDUdBRUpET0RhdGFzZXQYseQDDA/annotations",
"etag":"-1919132670",
"creationDate":null,
"stringAnnotations":{
"Disease":[
"Cancer"
],
"Tumor / Tissue Type":[
"Glioblastoma"
],
"Species":[
"Human"
],
"Institution":[
"TCGA"
],
"Reference / PubMed ID":[
"18772890" ]
},
"floatAnnotations":{
"Number of Samples":[
465.0
]
},
"dateAnnotations":{
}
}
Create a Dataset
Request:
curl -i -H Accept:application/json -H Content-Type:application/json
-d '{"name":"test dataset", "creator":"fake creator", "releaseDate":"2009-10-01", "status":"not curated"}'
http://localhost:8080/repo/v1/dataset
Response
HTTP/1.1 201 Created
ETag: 1736839268
Location: /repo/v1/dataset/agxkZWZsYXV4LXRlc3RyEwsSDUdBRUpET0RhdGFzZXQYBAw
Content-Type: application/json
Transfer-Encoding: chunked
Server: Jetty(6.1.x)
{
"name":"test dataset",
"annotations":"/repo/v1/dataset/agxkZWZsYXV4LXRlc3RyEwsSDUdBRUpET0RhdGFzZXQYAQw/annotations",
"id":"agxkZWZsYXV4LXRlc3RyEwsSDUdBRUpET0RhdGFzZXQYAQw",
"version":"0.0.1",
"creator":"fake creator",
"description":null,
"creationDate":1296595870715,
"status":"not curated",
"uri":"/repo/v1/dataset/agxkZWZsYXV4LXRlc3RyEwsSDUdBRUpET0RhdGFzZXQYAQw",
"etag":"1309185941",
"releaseDate":1254355200000,
"layers":[
{
"id":"agxkZWZsYXV4LXRlc3RyEwsSDUdBRUpET0RhdGFzZXQYAQw",
"type":"C",
"uri":"/datalayer/agxkZWZsYXV4LXRlc3RyEwsSDUdBRUpET0RhdGFzZXQYAQw"
},
{
"id":"agxkZWZsYXV4LXRlc3RyFQsSDUdBRUpET0RhdGFzZXQYiaECDA",
"type":"E",
"uri":"agxkZWZsYXV4LXRlc3RyFQsSDUdBRUpET0RhdGFzZXQYiaECDA"
},
{
"id":"agxkZWZsYXV4LXRlc3RyFQsSDUdBRUpET0RhdGFzZXQYmfIBDA",
"type":"G",
"uri":"/datalayer/agxkZWZsYXV4LXRlc3RyFQsSDUdBRUpET0RhdGFzZXQYmfIBDA"
}
]
}
Update a Dataset
Note that in the example below the creator and description fields have been changed but all others remain the same.
Request:
curl -i -H Accept:application/json -H Content-Type:application/json -X PUT -H ETag:1309185941 -d '{
"name":"test dataset",
"annotations":"/repo/v1/dataset/agxkZWZsYXV4LXRlc3RyEwsSDUdBRUpET0RhdGFzZXQYAQw/annotations",
"id":"agxkZWZsYXV4LXRlc3RyEwsSDUdBRUpET0RhdGFzZXQYAQw",
"version":"0.0.1",
"creator":"updated creator",
"description":"I just added a description",
"creationDate":1296595870715,
"status":"not curated",
"uri":"/repo/v1/dataset/agxkZWZsYXV4LXRlc3RyEwsSDUdBRUpET0RhdGFzZXQYAQw",
"etag":"1309185941",
"releaseDate":1254355200000,
"layers":[
{
"id":"agxkZWZsYXV4LXRlc3RyEwsSDUdBRUpET0RhdGFzZXQYAQw",
"type":"C",
"uri":"/datalayer/agxkZWZsYXV4LXRlc3RyEwsSDUdBRUpET0RhdGFzZXQYAQw"
},
{
"id":"agxkZWZsYXV4LXRlc3RyFQsSDUdBRUpET0RhdGFzZXQYiaECDA",
"type":"E",
"uri":"agxkZWZsYXV4LXRlc3RyFQsSDUdBRUpET0RhdGFzZXQYiaECDA"
},
{
"id":"agxkZWZsYXV4LXRlc3RyFQsSDUdBRUpET0RhdGFzZXQYmfIBDA",
"type":"G",
"uri":"/datalayer/agxkZWZsYXV4LXRlc3RyFQsSDUdBRUpET0RhdGFzZXQYmfIBDA"
}
]
}
' http://localhost:8080/repo/v1/dataset/agxkZWZsYXV4LXRlc3RyEwsSDUdBRUpET0RhdGFzZXQYAQw
Response
HTTP/1.1 200 OK
ETag: -852418664
Content-Type: application/json
Transfer-Encoding: chunked
Server: Jetty(6.1.x)
{
"name":"test dataset",
"annotations":"/repo/v1/dataset/agxkZWZsYXV4LXRlc3RyEwsSDUdBRUpET0RhdGFzZXQYAQw/annotations",
"id":"agxkZWZsYXV4LXRlc3RyEwsSDUdBRUpET0RhdGFzZXQYAQw",
"version":"0.0.1",
"creator":"updated creator",
"description":"I just added a description",
"creationDate":1296595870715,
"status":"not curated",
"uri":"/repo/v1/dataset/agxkZWZsYXV4LXRlc3RyEwsSDUdBRUpET0RhdGFzZXQYAQw",
"etag":"-852418664",
"releaseDate":1254355200000,
"layers":[
{
"id":"agxkZWZsYXV4LXRlc3RyEwsSDUdBRUpET0RhdGFzZXQYAQw",
"type":"C",
"uri":"/datalayer/agxkZWZsYXV4LXRlc3RyEwsSDUdBRUpET0RhdGFzZXQYAQw"
},
{
"id":"agxkZWZsYXV4LXRlc3RyFQsSDUdBRUpET0RhdGFzZXQYiaECDA",
"type":"E",
"uri":"agxkZWZsYXV4LXRlc3RyFQsSDUdBRUpET0RhdGFzZXQYiaECDA"
},
{
"id":"agxkZWZsYXV4LXRlc3RyFQsSDUdBRUpET0RhdGFzZXQYmfIBDA",
"type":"G",
"uri":"/datalayer/agxkZWZsYXV4LXRlc3RyFQsSDUdBRUpET0RhdGFzZXQYmfIBDA"
}
]
}
Add Annotations to a Dataset
First get the empty annotations container for your newly created dataset
Request
curl -i http://localhost:8080/repo/v1/dataset/agxkZWZsYXV4LXRlc3RyEwsSDUdBRUpET0RhdGFzZXQYAQw/annotations
Response
HTTP/1.1 200 OK
ETag: 923521
Content-Type: application/json
Transfer-Encoding: chunked
Server: Jetty(6.1.x)
{
"id":"agxkZWZsYXV4LXRlc3RyEwsSDUdBRUpET0RhdGFzZXQYAQw",
"creationDate":null,
"uri":"/repo/v1/dataset/agxkZWZsYXV4LXRlc3RyEwsSDUdBRUpET0RhdGFzZXQYAQw/annotations",
"etag":"923521",
"stringAnnotations":{
},
"floatAnnotations":{
},
"dateAnnotations":{
}
}
Then you add/modify the annotations of interest and do a PUT. Note that annotation values must always be list values even if the list is only of length one.
Request
curl -i -H Accept:application/json -H Content-Type:application/json -X PUT -H ETag:923521 -d '{
"id":"agxkZWZsYXV4LXRlc3RyEwsSDUdBRUpET0RhdGFzZXQYAQw",
"creationDate":null,
"uri":"/repo/v1/dataset/agxkZWZsYXV4LXRlc3RyEwsSDUdBRUpET0RhdGFzZXQYAQw/annotations",
"etag":"923521",
"stringAnnotations":{
"Experimental Design Templates":["exp-122887", "exp-97765"]
},
"floatAnnotations":{
"Number of Samples":[500]
},
"dateAnnotations":{
"Publication Date":["2011-01-15"]
}
}' http://localhost:8080/repo/v1/dataset/agxkZWZsYXV4LXRlc3RyEwsSDUdBRUpET0RhdGFzZXQYAQw/annotations
Response
HTTP/1.1 200 OK
ETag: -1638393853
Content-Type: application/json
Transfer-Encoding: chunked
Server: Jetty(6.1.x)
{
"id":"agxkZWZsYXV4LXRlc3RyEwsSDUdBRUpET0RhdGFzZXQYBww",
"creationDate":null,
"uri":"/repo/v1/dataset/agxkZWZsYXV4LXRlc3RyEwsSDUdBRUpET0RhdGFzZXQYBww/annotations",
"etag":"-1638393853",
"stringAnnotations":{
"Experimental Design Templates":[
"exp-122887",
"exp-97765"
]
},
"floatAnnotations":{
"Number of Samples":[
500.0
]
},
"dateAnnotations":{
"Publication Date":[
1295049600000
]
}
}
Delete a Dataset
Request
curl -i -X DELETE http://localhost:8080/repo/v1/dataset/agxkZWZsYXV4LXRlc3RyEwsSDUdBRUpET0RhdGFzZXQYAQw
Response
HTTP/1.1 204 No Content Server: Jetty(6.1.x)
Create a layer
Request
curl -i -H Accept:application/json -H Content-Type:application/json -d '{"name":"Flint HS Mice Affy", "type":"E", "description":"this is a description", "releaseNotes":"this is a release note"}' http://localhost:8080/repo/v1/dataset/agxkZWZsYXV4LXRlc3RyEwsSDUdBRUpET0RhdGFzZXQYUww/layer
Response
HTTP/1.1 201 Created
ETag: 1240467407
Location: /repo/v1/dataset/agxkZWZsYXV4LXRlc3RyEwsSDUdBRUpET0RhdGFzZXQYUww/layer/agxkZWZsYXV4LXRlc3RyLgsSDUdBRUpET0RhdGFzZXQYUwwLEhRHQUVKRE9JbnB1dERhdGFMYXllchjoBww
Content-Type: application/json
Transfer-Encoding: chunked
Server: Jetty(6.1.x)
{
"name":"Flint HS Mice Affy",
"annotations":"/repo/v1/dataset/agxkZWZsYXV4LXRlc3RyEwsSDUdBRUpET0RhdGFzZXQYUww/layer/agxkZWZsYXV4LXRlc3RyLgsSDUdBRUpET0RhdGFzZXQYUwwLEhRHQUVKRE9JbnB1dERhdGFMYXllchjoBww/annotations",
"id":"agxkZWZsYXV4LXRlc3RyLgsSDUdBRUpET0RhdGFzZXQYUwwLEhRHQUVKRE9JbnB1dERhdGFMYXllchjoBww",
"type":"E",
"version":"0.0.1",
"description":"this is a description",
"creationDate":1296690778880,
"uri":"/repo/v1/dataset/agxkZWZsYXV4LXRlc3RyEwsSDUdBRUpET0RhdGFzZXQYUww/layer/agxkZWZsYXV4LXRlc3RyLgsSDUdBRUpET0RhdGFzZXQYUwwLEhRHQUVKRE9JbnB1dERhdGFMYXllchjoBww",
"etag":"1240467407",
"publicationDate":null,
"releaseNotes":"this is a release note",
"tissueType":null,
"platform":null,
"processingFacility":null,
"qcBy":null,
"qcDate":null
}
Now ask for the owning dataset and you can see the preview of the layer
Request
curl -i http://localhost:8080/repo/v1/dataset/agxkZWZsYXV4LXRlc3RyEwsSDUdBRUpET0RhdGFzZXQYUww
Response
{
"name":"Flint HS Mice",
"annotations":"/repo/v1/dataset/agxkZWZsYXV4LXRlc3RyEwsSDUdBRUpET0RhdGFzZXQYUww/annotations",
"id":"agxkZWZsYXV4LXRlc3RyEwsSDUdBRUpET0RhdGFzZXQYUww",
"version":"0.0.1",
"creator":"Jonathan Flint",
"description":null,
"creationDate":1296690549675,
"status":"Future",
"uri":"/repo/v1/dataset/agxkZWZsYXV4LXRlc3RyEwsSDUdBRUpET0RhdGFzZXQYUww",
"etag":"-801135512",
"releaseDate":null,
"layers":[
Unknown macro: { "id"}
,
Unknown macro: { "id"}
]
}