| Table of Contents |
|---|
Introduction
The Query API is loosely modeled after Facebook's Query Language.
The REST API took inspiration from several successful REST APIs:
- Facebook's Graph API
- Google's Data Protocol
- The Open Data Protocol
See Service API Design for more information regarding the rationale and design details for this api.
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 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'
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 a Dataset
Request
| Code Block |
|---|
curl -i -H Accept:application/json "http://deflaux-test.appspot.com/repo/v1/dataset/agxkZWZsYXV4LXRlc3RyFQsSDUdBRUpET0RhdGFzZXQYseQDDA"
|
Response
...
Security
Eventually these services will be HTTPS only and disallow HTTP. For all requests requiring authentication, users will pass a special header sessionToken with
each request to the service.
Log into Synapse
You must have an account with permission to create entities in Synapse.
Request
| Code Block |
|---|
curl -i -k -H Accept:application/json -H Content-Type:application/json -d '{
"email": "me@myEmail.com",
"password": "thisIsAFakePassword"
}' https://auth-prod.sagebase.org/auth/v1/session |
Response
| Expand | |||||||||
|---|---|---|---|---|---|---|---|---|---|
| |||||||||
|
Create/Update/Delete Examples
You can create entities, update entities, read entities, and delete entities. More advanced querying is 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. Conflicting updates are detected and rejected through the use of the ETag header.
Create a Entity
An entity is created with a POST where the entity body is passed with a content type of application/json. The only required property for any entity is the 'entityType' which indicates the type of entity you wish to create. See the following table for common entity types:
| entityType | Alias (for query) | Description |
|---|---|---|
| org.sagebionetworks.repo.model.Project | project | A project entity serves as the root for collaboration. It is a common practices to place all other entities within a project. |
| org.sagebionetworks.repo.model.Folder | folder | A simple tool for organizing entities. This is similar to a file folder. |
| org.sagebionetworks.repo.model.Link | link | An entity that points to another entity, similar to a Window's Short Cut or a Linux/Mac Link. |
| org.sagebionetworks.repo.model.Code | code | An entity where the location is composed of source code. |
| org.sagebionetworks.repo.model.PhenotypeData | phenotypedata | Used for phenotypic data. |
| org.sagebionetworks.repo.model.GenotypeData | genotypedata | Used for genotypic data. |
| org.sagebionetworks.repo.model.ExpressionData | expressiondata | Used for expression data. |
| org.sagebionetworks.repo.model.RObject | robject | Language specific 'R' object. |
| org.sagebionetworks.repo.model.Study | study | Used for a study. |
| org.sagebionetworks.repo.model.Data | data | Generic data. |
For more information on entity types see: Synapse Entity Types.
Note that the request is a POST and the content type of the data we are sending to the service is json
In the following example we are going to create a project entity:
Request
| Code Block |
|---|
curl -i -k -H sessionToken:YourSessionToken -H Accept:application/json -H Content-Type:application/json -d '{"entityType": "org.sagebionetworks.repo.model.Project"}' https://repo-prod.sagebase.org/repo/v1/entity |
Response
| Expand | ||
|---|---|---|
| ||
|
In the above example, we created an entity with only the 'entityType' but the returned entity had many more fields set. In the next section we will cover the basic fields of an entity.
Basic Entity Fields
The following are fields that are common to all entities and entity types:
| Field Name | Type | Description | Editable | Default Value |
|---|---|---|---|---|
| id | String | The ID issued to this entity by Synapse to unique identify it. This ID is immutable and guaranteed to be unique within Synapse. Once an ID is issue to entity the ID will never be issued to another entity even if the original entity is deleted. | false | auto-generated |
parentId | String | This is the ID of this entity's parent. This is used to build a hierarchy of entities. | true | Root folder |
createdOn | ISO 8601 date-time | The date and time when the entity was original created. | false | auto-generated |
modifiedOn | ISO 8601 date-time | The date and time when the entity was last modified. | false | auto-generated |
createdBy | String | The name of the user that originally created the entity. | false | auto-generated |
modifiedBy | String | The name of the user that last modified the entity. | false | auto-generated |
name | String | The name of the entity. This is the most prominent fields of the entity and will show up everywhere. Just like a file must have a unique name within a folder, an Entity must have a unique name within its parent. | true | entity id |
| description | String | The description provides more details about an Entity. This field is very prominent on the Synapse web site. | true | null |
etag | String | Used to concurrency and change detection. | false | auto-generated |
uri | String | Relative URI of the entity. | false | auto-generated |
annotations | String | The relative URL for the entity annotations. | false | auto-generated |
accessControlList | String | The relative URL for the entity Access Control List ACL. | false | auto-generated |
Any editable field can be set at creation time or updated.
Update an Entity
In this example we want to give our project entity from the previous example a more meaningful name (the default name is the same as the entity's id) .
Note that the request is a PUT. Also note that we add a header 'ETag' with a value that is the same as current etag of the entity. If the entity has been modified since we last fetched it the etag will not match and we will receive a concurrent modification error.
Request
| Code Block |
|---|
curl -i -k -H sessionToken:YourSessionToken -H ETag:0 -H Accept:application/json -H Content-Type:application/json -X PUT -d '{
"createdOn":"2012-08-29T03:34:00.967Z",
"id":"syn1058078",
"parentId":"syn4489",
"modifiedOn":"2012-08-29T03:34:00.967Z",
"createdBy":"John Hill",
"accessControlList":"/repo/v1/entity/syn1058078/acl",
"etag":"0",
"modifiedBy":"John Hill",
"name":"Example Project",
"annotations":"/repo/v1/entity/syn1058078/annotations",
"entityType":"org.sagebionetworks.repo.model.Project",
"uri":"/repo/v1/entity/syn1058078"
}' https://repo-prod.sagebase.org/repo/v1/entity/syn1058078 |
Response
| Expand | ||
|---|---|---|
| ||
|
Creating Hierarchy
Hierarchy is created in Synapse by setting the "parentId" field of an entity. In this example we are going to create a new folder entity as a child to our project:
Request
| Code Block |
|---|
curl -i -k -H sessionToken:YourSessionToken -H Accept:application/json -H Content-Type:application/json -d '{"entityType": "org.sagebionetworks.repo.model.Data", "parentId":"syn1058078", "name":"Sample Data"}' https://repo-prod.sagebase.org/repo/v1/entity |
Response
| Expand | ||
|---|---|---|
| ||
|
Entity Annotations
Get Annotations
First get the current annotations for your newly created data entity.
Request
| Code Block |
|---|
curl -i -k -H sessionToken:YourSessionToken -H Accept:application/json https://repo-prod.sagebase.org/repo/v1/entity/syn1151499/annotations |
Response
| Expand | ||
|---|---|---|
| ||
|
Update Annotations
Then you add new annotations to the existing annotations, or modify the existing annotations, and do a PUT. Note that annotation values must always be arrays even if the array is only of length one.
Request
| Code Block |
|---|
curl -i -k -H sessionToken:YourSessionToken -H ETag:843bddfc-d6f8-45d2-b88e-09b4aa27a1cf -H Accept:application/json -H Content-Type:application/json -X PUT -d '
{
"id":"syn1151499",
"creationDate":"1347503586314",
"stringAnnotations":{
"stringExampleA":[
"one",
"two"
],
"stringExampleB":[
"cat",
"dog"
]
},
"dateAnnotations":{
"dateExample":[
1347519600000,
1347606000000
]
},
"etag":"843bddfc-d6f8-45d2-b88e-09b4aa27a1cf",
"doubleAnnotations":{
"floatExample":[
1.234,
99.789
]
},
"longAnnotations":{
"longExample":[
123,
456879
]
},
"blobAnnotations":{
},
"uri":"/entity/syn1151499/annotations"
}' https://repo-prod.sagebase.org/repo/v1/entity/syn1151499/annotations |
Response
| Expand | ||
|---|---|---|
| ||
|
Set Entity Location
In this example we will be uploading a simple text file with the following content:
| Code Block |
|---|
Some simple text! |
We will need to know the md5 of our file before we start. For this example the text the MD5 is:
| Code Block |
|---|
6b65ca38d3596e0e0e6e1ed3cfa981eb |
There are three steps required to set an Entity's location data:
- Create an S3 Token. We will use this token to upload the file to Amazon's S3.
Request
Code Block curl -i -k -H sessionToken:YourSessionToken -H Accept:application/json -H Content-Type:application/json -d '{"path": "SampleTextFile.txt", "md5":"6b65ca38d3596e0e0e6e1ed3cfa981eb"}' https://repo-prod.sagebase.org/repo/v1/entity/syn1151499/s3TokenResponse
Expand title [Click to show] Code Block { "sessionToken":"AQoDYXdzEG4asAKFXWZXVmnAG7q1zyUzRjVz6rnN6wIRT0msXgSRBC3suTAItfuQjJRv9YOAw3Fr4nlJL2HAnRbNvF1NC4xnW5+j6VUNnJYGtZUj+wii+bTGYncNrruXLxqqLM8Kg/dmGQGWluVZkYy7rLDbofrWcWunRjSYBb7uEe74EURM1jg1ae3qMnNgwBUHWJvJb1AjOojpNujh0N5KX0C3ux6VCDcFrgHR6K+siyfiPqSW25XmabA5jGAnV6EGXn1iazywrl2ZW8z+fYAZB1kgsoTCQgCZMsPxpXxh/BdQi7cc7rwflCr/P1wD51N9PGFakFhJkbm8glGhE+YQDYEOpvRmOF0+S2+xrstIzsEAoZ5NXmMg97pqOWx1sBQVvKp8NXgdkXn422CFJLFPW8u+Vd/HzO6EILnQxYIF", "secretAccessKey":"XXXXXXXXXXXXXXXXX", "bucket":"proddata.sagebase.org", "path":"/1151499/1159148/SampleTextFile.txt", "accessKeyId":"XXXXXXXXXXXXXXXXXXXX", "md5":"6b65ca38d3596e0e0e6e1ed3cfa981eb", "contentType":"text/plain", "presignedUrl":"https://s3.amazonaws.com/proddata.sagebase.org/1151499/1159148/SampleTextFile.txt?Expires=1347598777&x-amz-security-token=AQoDYXdzEG4asAKFXWZXVmnAG7q1zyUzRjVz6rnN6wIRT0msXgSRBC3suTAItfuQjJRv9YOAw3Fr4nlJL2HAnRbNvF1NC4xnW5%2Bj6VUNnJYGtZUj%2Bwii%2BbTGYncNrruXLxqqLM8Kg%2FdmGQGWluVZkYy7rLDbofrWcWunRjSYBb7uEe74EURM1jg1ae3qMnNgwBUHWJvJb1AjOojpNujh0N5KX0C3ux6VCDcFrgHR6K%2BsiyfiPqSW25XmabA5jGAnV6EGXn1iazywrl2ZW8z%2BfYAZB1kgsoTCQgCZMsPxpXxh%2FBdQi7cc7rwflCr%2FP1wD51N9PGFakFhJkbm8glGhE%2BYQDYEOpvRmOF0%2BS2%2BxrstIzsEAoZ5NXmMg97pqOWx1sBQVvKp8NXgdkXn422CFJLFPW8u%2BVd%2FHzO6EILnQxYIF&AWSAccessKeyId=ASIAIGRZMDNEEK777KGA&Signature=c%2BC0HOBQ2MOzS4L89ev4OPbzD1w%3D" }
- Use the "presignedUrl" from the previous step to upload the file to Amazon S3: Note: For more information on uploading files to S3 see: http://docs.amazonwebservices.com/AmazonS3/latest/API/RESTObjectPUT.html
Request
Code Block curl -v -k -X PUT -H Content-MD5:a2XKONNZbg4Obh7Tz6mB6w== -H x-amz-acl:bucket-owner-full-control -H Content-Type:text/plain --data-ascii SampleTextFile.txt https://s3.amazonaws.com/proddata.sagebase.org/1151499/1159148/SampleTextFile.txt?Expires=1347598777&x-amz-security-token=AQoDYXdzEG4asAKFXWZXVmnAG7q1zyUzRjVz6rnN6wIRT0msXgSRBC3suTAItfuQjJRv9YOAw3Fr4nlJL2HAnRbNvF1NC4xnW5%2Bj6VUNnJYGtZUj%2Bwii%2BbTGYncNrruXLxqqLM8Kg%2FdmGQGWluVZkYy7rLDbofrWcWunRjSYBb7uEe74EURM1jg1ae3qMnNgwBUHWJvJb1AjOojpNujh0N5KX0C3ux6VCDcFrgHR6K%2BsiyfiPqSW25XmabA5jGAnV6EGXn1iazywrl2ZW8z%2BfYAZB1kgsoTCQgCZMsPxpXxh%2FBdQi7cc7rwflCr%2FP1wD51N9PGFakFhJkbm8glGhE%2BYQDYEOpvRmOF0%2BS2%2BxrstIzsEAoZ5NXmMg97pqOWx1sBQVvKp8NXgdkXn422CFJLFPW8u%2BVd%2FHzO6EILnQxYIF&AWSAccessKeyId=ASIAIGRZMDNEEK777KGA&Signature=c%2BC0HOBQ2MOzS4L89ev4OPbzD1w%3D
- Once the file has been successfully uploaded to S3 update the Entity using the S3 Token:
Request
Code Block curl -i -k -H sessionToken:YourSessionToken -H ETag:2526dd09-565e-4989-b8c4-a82e724672c6 -H Accept:application/json -H Content-Type:application/json -X PUT -d '{ "s3Token":"/repo/v1/entity/syn1151499/s3Token", "versionLabel":"0.0.0", "etag":"2526dd09-565e-4989-b8c4-a82e724672c6", "accessControlList":"/repo/v1/entity/syn1151499/acl", "versionUrl":"/repo/v1/entity/syn1151499/version/1", "modifiedBy":"John Hill", "contentType":"text/plain", "entityType":"org.sagebionetworks.repo.model.Data", "uri":"/repo/v1/entity/syn1151499", "id":"syn1151499", "createdOn":"2012-09-12T19:33:06.314-07:00", "modifiedOn":"2012-09-12T19:44:39.544-07:00", "parentId":"syn1058078", "versions":"/repo/v1/entity/syn1151499/version", "createdBy":"John Hill", "locations":[ { "path":"/1151499/1158826/SampleTextFile.txt", "type":"awss3" } ], "name":"Sample Data", "md5":"6b65ca38d3596e0e0e6e1ed3cfa981eb", "annotations":"/repo/v1/entity/syn1151499/annotations", "versionNumber":1 }' https://repo-prod.sagebase.org/repo/v1/entity/syn1151499Response
Expand title [Click to show] Code Block HTTP/1.1 200 OK Content-Type: application/json Date: Thu, 13 Sep 2012 05:10:20 GMT ETag: 0bf4af7b-0dc9-4c5c-9454-3931bcf08a17 Server: Apache-Coyote/1.1 Content-Length: 1382 Connection: keep-alive { "s3Token":"/repo/v1/entity/syn1151499/s3Token", "versionLabel":"0.0.0", "etag":"0bf4af7b-0dc9-4c5c-9454-3931bcf08a17", "accessControlList":"/repo/v1/entity/syn1151499/acl", "versionUrl":"/repo/v1/entity/syn1151499/version/1", "modifiedBy":"John Hill", "contentType":"text/plain", "entityType":"org.sagebionetworks.repo.model.Data", "uri":"/repo/v1/entity/syn1151499", "id":"syn1151499", "createdOn":"2012-09-13T02:33:06.314Z", "modifiedOn":"2012-09-13T05:12:26.121Z", "parentId":"syn1058078", "versions":"/repo/v1/entity/syn1151499/version", "createdBy":"John Hill", "locations":[ { "path":"https://s3.amazonaws.com/proddata.sagebase.org/1151499/1158826/SampleTextFile.txt?Expires=1347599546&x-amz-security-token=AQoDYXdzEG4asAKml38O7Ej08SS50xD7p84phJD9YjcylB6FmjsrDCyGKdb7rpC8GsZloCFT3jd5pVdLDMo58SgDFYNPZjGzg%2BpA6AWk0HTIirwdJvQCdq2KnImv3NMWmvnULs%2B%2Fbbkl6V6C0EPK5W8EhZsCtH55zuOofEpVnNk9BrhhU0VcmStaCevCv6eaCHJw5DsmIsnOlKswGnoibuEAh7WA2JTTU4sg6aDrzYCnDL6MgGxxtnNw7%2B5N9GPmrfLRk7NdqqF2NulYpv%2BH5ZmALdW1YjRAB8C9o9SGPX8nQci1e2r5cGIJyNc6kuw1Fzs0vhRKBH3Jz%2FMR3hdqE7zQmMp5x%2F4eAtgm09GKhPC1kH%2BJdrMFP0i6N%2BmPsQVF4lNx0yhVCwIbC%2BRxYFAIzmiredqAKbvhsOKeILrWxYIF&AWSAccessKeyId=ASIAJNRHQYY4PXQAD3YA&Signature=jtY54hJMHqhWoBiHEsbVIUWipuQ%3D", "type":"awss3" } ], "name":"Sample Data", "md5":"6b65ca38d3596e0e0e6e1ed3cfa981eb", "annotations":"/repo/v1/entity/syn1151499/annotations", "versionNumber":1 }
Versions Create/Read/Update/Delete (and Promote)
Any leaf entity that is version-able will have additional metada. Here is the JSON schema for these additional fields:
| Code Block |
|---|
{
"properties": {
"versionLabel": {"type": "string"},
"versionNumber": {"type": "number"},
"versionUrl": {"type": "string"},
"versions": {"type": "string"},
"versionComment" {"type": "string"},
},
"type": "object"
}
|
Field Name | User Provided / Auto-generated | Description |
|---|---|---|
versionLabel | User Provided | The user visible label for this revision. It is up to the user to provide a meaningful label |
versionComment | User Provided | The user provided comment for this version. For example, what is this version, and why was it created? |
versionNumber | Auto-generate | The contiguous number representing this version. The first version will be '1', followed by '2'...'n' |
versionUrl | Auto-generated | The URL that can be used to fetch this version of the entity |
versions | Auto-generated | The URL to list all versions of this entity |
Version-able Entity Metadata
For version-able Entities, some metadata applies to the root object and is therefore version independent, while other metadata applies to the version and is therefore, version dependent. For example, the Access Control List (ACL) of an entity is version independent. This means it is not possible to apply different permissions to different versions of an entity. While the Annotations of an entity are version dependent. This means each version of the same entity can have different Annotations. The following table lists the various entity metadata and whether it is version dependent or independent.
Metadata | Version Dependent /Independent | Implications |
|---|---|---|
Access Control List | Independent | Access to all versions is controlled with a single ACL |
Name | Independent | One name applies to all versions of an entity |
Description | Independent | One description applies to all versions of an entity |
Created-On | Independent | An entity can only be created once |
Created-By | Independent | An entity can only be created once |
Parent-Id | Independent | All version of an entity must have the same parent |
Annotations | Dependent | Each version of an entity can have its own annotations |
Modified-By | Dependent | First set when a new version is created, and updated every time its version is change. Once a new version is created the Modified-By fields of older versions will remain static as older versions are immutable |
Modified-On | Dependent | First set when a new version is created, and updated every time its version is change. Once a new version is created the Modified-On fields of older versions will remain static as older versions are immutable |
All Entity specific matadata | Dependent | Each version of an entity can have its own values for all entity specific metadata. For example, the Location.path can have a unique value for each version. |
Current API
The following table describes how versioning effects the current entity CRUD API:
URL | HTTP Type | Description |
|---|---|---|
/{entityType} | POST | Creates a new entity of the given {entityType}. For version-able entities, this will create the first version of this entity. This entity will have a versionNumber=1 |
/{entityType} | GET | Get a list of all entities of the given type: {entityType}. For version-able entity types, this will list the current version of each entity of that type. |
/{entityType}/{id} | GET | Get an entity using its type and id. For version-able entities this will return the current version of the entity. |
/{entityType}/{id} | PUT | Update the entity identified by type and id. For a version-able entity this will update the current version of the entity. |
/{entityType}/{id} | DELETE | Delete the entity identified by type and id. For a version-able entity this will delete the entity and all versions of the entity. |
/{entityType}/{id}/annotations | GET | Get the annotations for the entity identified by type and id. For a version-able entity this will return the annotations of the current entity. |
/{entityType}/{id}/annotations | PUT | Update the annotations for the entity identified by type and id. For a version-able entity this will update the annotations of the current entity. |
Version-able Additions to the API
The following table describes the new methods for manipulating the versions of a version-able entity.
URL | HTTP Type | Description |
|---|---|---|
/{versionable-entityType}/{entityId}/version | PUT | Create a new version of a given version-able entity. The user should provide a versionLabel and Synapse will auto-generate a new versionNumber. When this called on a version-able entity, the annotations of the current entity will be copied and applied to the newly created version. |
/{versionable-entityType}/{entityId}/version | GET | Returns a list of all versions of this entity. This will be a paginated list with a default sort on versionNumber descending |
/{versionable-entityType}/{entityId}/version/{versionNumber} | GET | Get a particular version of a version-able entity using the given id and version number. Note that the specific version fetched cannot be used to update the current version. Instead, promote it to the current version. |
/{versionable-entityType}/{entityId}/version/{versionNumber} | PUT | Not supported! Only the current version of an entity can be updated using the existing API. |
/{versionable-entityType}/{entityId}/version/{versionNumber} | DELETE | Delete a particular version of a version-able entity using the given id and version number. |
/{versionable-entityType}/{entityId}/version/{versionNumber}/annotations | GET | Get the annotations of a particular version of a version-able entity using the given id and version number. |
/{versionable-entityType}/{entityId}/version/{versionNumber}/annotations | PUT | Not Supported! You can only change the annotations of the current version. |
| /{versionable-entityType}/{entityId}/promoteVersion/{versionNumber} | POST | Promote the specified versionNumber to be the current version. Effectively, this just changes the number of that version to be current + 1. |
Version API Examples:
Get the Location to Version
Get the location object we created earlier:
Request
| Code Block |
|---|
curl -i -H sessionToken:YourSessionToken -H Accept:application/json 'https://repo-staging.sagebase.org/repo/v1/location/17338' |
Response
| Expand | ||
|---|---|---|
| ||
|
Create New Version
To create a new version of a location, we set the version comment and label. We also want to set a new path for this version:
Request
| Code Block |
|---|
curl -i -H sessionToken:YourSessionToken -H ETag:0 -H Accept:application/json -H Content-Type:application/json -X PUT -d '{
"contentType": "application/zip",
"etag": "0",
"id": "17338",
"md5sum": "b513a23fc54b7b0d65312e1a900af5a6",
"name": "17338",
"parentId": "17337",
"path": "https://s3.amazonaws.com/stagingdata.sagebase.org/17338/0.0.2/mskcc_prostate_cancer.phenotype.zip?Expires=1317918889&AWSAccessKeyId=AKIAJQBSYCAUPIYF5WTA&Signature=2vTczuWgJ88Z0tiau1%2BPse4L2NA%3D",
"type": "awss3",
"uri": "/repo/v1/location/17338",
"versionComment": "The second version of this location.",
"versionLabel": "0.0.2"
}' https://repo-staging.sagebase.org/repo/v1/location/17338/version |
Response
| Expand | ||
|---|---|---|
| ||
|
List Versions
List all of the version of this location. The current version will be the first in the list:
Request
| Code Block |
|---|
curl -i -H sessionToken:YourSessionToken -H Accept:application/json 'https://repo-staging.sagebase.org/repo/v1/location/17338/version' |
Response
| Expand | ||
|---|---|---|
| ||
|
Get a Previous Version
To get a previous version we must provide the version number we would like to fetch:
Request
| Code Block |
|---|
curl -i -H sessionToken:YourSessionToken -H Accept:application/json 'https://repo-staging.sagebase.org/repo/v1/location/17338/version/1' |
Response
| Expand | ||
|---|---|---|
| ||
|
Get Annotations of a Previous Version
To get the annotations of a previous version we must provide the version number we would like to fetch:
Request
| Code Block |
|---|
curl -i -H sessionToken:YourSessionToken -H Accept:application/json 'https://repo-staging.sagebase.org/repo/v1/location/17338/version/1/annotations' |
Response
| Expand | ||
|---|---|---|
| ||
|
Delete a Version
To delete a specific versoin we must provide the version number. Note: You cannot delete the last version of an entity.
Request
| Code Block |
|---|
curl -i -H sessionToken:YourSessionToken -H Accept:application/json -X DELETE https://repo-staging.sagebase.org/repo/v1/location/17338/version/1 |
Response
| Expand | ||
|---|---|---|
| ||
|
Promote a Version
To promote a specific version we must provide the version number. Note: you can promote the current version of an entity, but it is a no-op
Request
| Code Block |
|---|
curl -i -H sessionToken:YourSessionToken -H Accept:application/json -X DELETE https://repo-staging.sagebase.org/repo/v1/location/17338/promoteVersion/1 |
Response
| Expand | ||
|---|---|---|
|
Finally List Versions Again
List all of the version of this location. Since we deleted the first version, only the second remains:
Request
| Code Block |
|---|
curl -i -H sessionToken:YourSessionToken -H Accept:application/json 'https://repo-staging.sagebase.org/repo/v1/location/17338/version' |
Response
| Expand | ||
|---|---|---|
| ||
|
Delete a Project
Note that the request is a DELETE and no content is returned. Also note that this will delete all of the datasets layers, etc.
Request
| Code Block |
|---|
curl -i -H sessionToken:YourSessionToken -H Accept:application/json -X DELETE https://repo-staging.sagebase.org/repo/v1/project/17334 |
Response
| Expand | ||
|---|---|---|
| ||
|
Query API
The Query API is loosely modeled after Facebook's Query Language.
Examples
'Select *' Query
These queries are generally of the form:
| Code Block |
|---|
SELECT * FROM <data type> [LIMIT <#>] [OFFSET <#>] |
Currently supported data types:
| <data type> |
|---|
| project |
| folder |
file entity |
Request
| Code Block |
|---|
curl -i -H sessionToken:YourSessionToken -H Accept:application/json 'https://repo-staging.sagebase.org/repo/v1/query?query=select+*+from+dataset+limit+3+offset+1' |
Response
| Expand | ||
|---|---|---|
| ||
|
'Order By' Query
These queries are generally of the form:
| Code Block |
|---|
SELECT * FROM <data type> ORDER BY <field name> [ASC|DESC] [LIMIT <#>] [OFFSET #] |
Request
| Code Block |
|---|
curl -i -H sessionToken:YourSessionToken -H Accept:application/json 'https://repo-staging.sagebase.org/repo/v1/query?query=select+*+from+dataset+order+by+Number_of_Samples+DESC+limit+3+offset+1' |
Response
| Expand | ||
|---|---|---|
| ||
|
Single clause 'Where' Query
These queries are generally of the form:
| Code Block |
|---|
SELECT * FROM <data type> WHERE <expression> (AND <expression>)* [LIMIT <#>] [OFFSET #]
<expresssion> := <field name> <operator> <value> |
<value> should be in quotes for strings, but not numbers (i.e. name == "Smith" AND size > 10)
Curently supported <operators> with their required URL escape codes:
Operator | Value | URL Escape Code |
|---|---|---|
Equal | == | %3D%3D |
Does Not equal | != | !%3D |
Greater Than | > | %3E |
Less than | < | %3C |
Greater than or equals | >= | %3E%3D |
Less than or equals | <= | %3C%3D |
Request
| Code Block |
|---|
curl -i -H sessionToken:YourSessionToken -H Accept:application/json 'https://repo-staging.sagebase.org/repo/v1/query?query=select+*+from+dataset+where+name+==+%22MSKCC+Prostate+Cancer%22' |
Response
| Expand | ||
|---|---|---|
| ||
|
Multiple clause 'Where' Query
These queries are generally of the form:
| Code Block |
|---|
SELECT * FROM <data type> WHERE <expression> (AND <expression>)* [LIMIT <#>] [OFFSET #]
<expresssion> := <field name> <operator> <value> |
<value> should be in quotes for strings, but not numbers (i.e. name == "Smith" AND size > 10)
Curently supported <operators> with their required URL escape codes:
Operator | Value | URL Escape Code |
|---|---|---|
Equal | == | %3D%3D |
Does Not equal | != | !%3D |
Greater Than | > | %3E |
Less than | < | %3C |
Greater than or equals | >= | %3E%3D |
Less than or equals | <= | %3C%3D |
Request
| Code Block |
|---|
curl -i -H sessionToken:YourSessionToken -H Accept:application/json 'https://repo-staging.sagebase.org/repo/v1/query?query=select+*+from+dataset+where+dataset.Species+==+%22Human%22+and+dataset.Number_of_Samples+%3E+100+limit+3+offset+1' |
Response
| Expand | ||
|---|---|---|
| ||
|
'Select *' Query for the Layers of a Dataset
These queries are generally of the form:
| Code Block |
|---|
SELECT * FROM layer WHERE parentId == <parentId> [LIMIT <#>] [OFFSET <#>] |
Request
| Code Block |
|---|
curl -i -H sessionToken:YourSessionToken -H Accept:application/json 'https://repo-staging.sagebase.org/repo/v1/query?query=select+*+from+layer+where+layer.parentId+==+%223733%22' |
Response
| Expand | ||
|---|---|---|
| ||
|
'Order By' Query for the Layers of a Dataset
These queries are generally of the form:
| Code Block |
|---|
SELECT * FROM layer WHERE parentId == <parentId> ORDER BY <field name> [ASC|DESC] [LIMIT <#>] [OFFSET <#>] |
Request
| Code Block |
|---|
curl -i -H sessionToken:YourSessionToken -H Accept:application/json 'https://repo-staging.sagebase.org/repo/v1/query?query=select+*+from+layer+where+layer.parentId+==+%223733%22+ORDER+BY+type' |
Response
| Expand | ||
|---|---|---|
| ||
|
'Select *' Query for the all the people who have agreed to the terms in the End User License Agreement for a Dataset
These queries are generally of the form:
| Code Block |
|---|
SELECT * FROM <data type> WHERE <expression> (AND <expression>)* [LIMIT <#>] [OFFSET #]
<expresssion> := <field name> <operator> <value> |
<value> should be in quotes for strings, but not numbers (i.e. name == "Smith" AND size > 10)
Curently supported <operators> with their required URL escape codes:
Operator | Value | URL Escape Code |
|---|---|---|
Equal | == | %3D%3D |
Does Not equal | != | !%3D |
Greater Than | > | %3E |
Less than | < | %3C |
Greater than or equals | >= | %3E%3D |
Less than or equals | <= | %3C%3D |
Request
| Code Block |
|---|
curl -i -H sessionToken:YourSessionToken -H Accept:application/json 'https://repo-staging.sagebase.org/repo/v1/query?query=select+*+from+agreement+where+agreement.datasetId+==+%223733%22' |
Response
| Expand | ||
|---|---|---|
| ||
|
Schema
Query Response Schema
The JsonSchema is an emerging standard similar to DTDs for XML.
Request
| Code Block |
|---|
curl -i -H sessionToken:YourSessionToken -H Accept:application/json 'https://repo-staging.sagebase.org/repo/v1/query/schema' |
Response
| Expand | ||
|---|---|---|
| ||
|
REST API
The REST API took inspiration from several successful REST APIs:
- Facebook's Graph API
- Google's Data Protocol
- The Open Data Protocol
Read-Only Examples
Get All Datasets
Optional Parameters
- offset - integer - 1-based pagination offset
- limit - integer - maximum number of results to return
- sort - string - the name of the field upon which to sort
- ascending - boolean - whether or not to sort ascending
Request
| Code Block |
|---|
curl -i -H sessionToken:YourSessionToken -H Accept:application/json 'https://repo-staging.sagebase.org/repo/v1/dataset?sort=name&limit=3' |
Response
| Expand | ||
|---|---|---|
| ||
|
Get a Dataset
This returns the primary fields of a dataset and links to get additional info.
Request
| Code Block |
|---|
curl -i -H sessionToken:YourSessionToken -H Accept:application/json 'https://repo-staging.sagebase.org/repo/v1/dataset/3733' |
Response
| Expand | ||
|---|---|---|
| ||
|
Get Annotations for a Dataset
This returns the annotations for a dataset.
Request
| Code Block |
|---|
curl -i -H sessionToken:YourSessionToken -H Accept:application/json 'https://repo-staging.sagebase.org/repo/v1/dataset/3733/annotations' |
Response
| Expand | ||
|---|---|---|
| ||
|
Get all the Layers for a Dataset
This returns the primary fields for all the layers of a dataset.
Request
| Code Block |
|---|
curl -i -H sessionToken:YourSessionToken -H Accept:application/json 'https://repo-staging.sagebase.org/repo/v1/dataset/3733/layer' |
Response
| Expand | ||
|---|---|---|
| ||
|
Get a Clinical Dataset Layer
This returns the metadata for a dataset layer.
Request
| Code Block |
|---|
curl -i -H sessionToken:YourSessionToken -H Accept:application/json 'https://repo-staging.sagebase.org/repo/v1/layer/3874' |
Response
| Expand | ||
|---|---|---|
| ||
|
Get Annotations for a Clinical Dataset Layer
This returns the annotations for a dataset layer.
Request
| Code Block |
|---|
curl -i -H sessionToken:YourSessionToken -H Accept:application/json 'https://repo-staging.sagebase.org/repo/v1/layer/3874/annotations' |
Response
| Expand | ||
|---|---|---|
| ||
|
Get the Eula for a Clinical Dataset
This returns the eula for a dataset.
Request
| Code Block |
|---|
curl -i -H sessionToken:YourSessionToken -H Accept:application/json 'https://repo-staging.sagebase.org/repo/v1/eula/3732' |
Response
| Expand | ||
|---|---|---|
| ||
|
Get preview data for a Clinical Dataset Layer
This returns the preview data for a dataset layer.
Request
| Code Block |
|---|
curl -i -H sessionToken:YourSessionToken -H Accept:application/json 'https://repo-staging.sagebase.org/repo/v1/layer/3874/preview' |
Response
| Expand | ||
|---|---|---|
| ||
|
Get preview data as a map for a Clinical Dataset Layer
This returns the preview data for a dataset layer.
Request
| Code Block |
|---|
curl -i -H sessionToken:YourSessionToken -H Accept:application/json 'https://repo-staging.sagebase.org/repo/v1/layer/3874/preview' |
Response
| Expand | ||
|---|---|---|
| ||
|
Get the locations for a Clinical Dataset Layer
This returns all the locations metadata for a dataset layer.
Request
| Code Block |
|---|
curl -i -H sessionToken:YourSessionToken -H Accept:application/json 'https://repo-staging.sagebase.org/repo/v1/layer/3874/location' |
Response
| Expand | ||
|---|---|---|
| ||
|
Get the awss3 for a Clinical Dataset Layer
This returns the location data for a dataset layer.
Request
| Code Block |
|---|
curl -i -H sessionToken:YourSessionToken -H Accept:application/json 'https://repo-staging.sagebase.org/repo/v1/location/3875' |
Response
| Expand | ||
|---|---|---|
| ||
|
An example to fetch the file using curl:
| Code Block |
|---|
curl -o local/path/to/file.zip 'https://s3.amazonaws.com/stagingdata.sagebase.org/3875/0.0.0/mskcc_prostate_cancer.phenotype.zip?Expires=1317918906&AWSAccessKeyId=AKIAJQBSYCAUPIYF5WTA&Signature=Rb%2BXDamGfltAbWKGZsifuo0qdgA%3D' |
An example to conditionally fetch the file using curl:
| Code Block |
|---|
curl -i -H If-None-Match:b513a23fc54b7b0d65312e1a900af5a6 'https://s3.amazonaws.com/stagingdata.sagebase.org/3875/0.0.0/mskcc_prostate_cancer.phenotype.zip?Expires=1317918906&AWSAccessKeyId=AKIAJQBSYCAUPIYF5WTA&Signature=Rb%2BXDamGfltAbWKGZsifuo0qdgA%3D'
HTTP/1.1 304 Not Modified
x-amz-id-2: h3qt9NfdRw7utcyVMCZF/dNRto9ZpmKY56w69HNpuMkNsaDv9MgduGY9L3zBQWl
x-amz-request-id: 3AADDC9EF832ADD2
Date: Tue, 07 Jun 2011 18:40:15 GMT
Last-Modified: Tue, 05 Apr 2011 00:42:50 GMT
ETag: "b513a23fc54b7b0d65312e1a900af5a6"
Server: AmazonS3 |
Get the awss3 for a Clinical Dataset Layer for HTTP method HEAD
This returns the location data for a dataset layer with the S3 URL presigned for a HEAD request instead of the default GET.
Request
| Code Block |
|---|
curl -i -H sessionToken:YourSessionToken -H Accept:application/json 'https://repo-staging.sagebase.org/repo/v1/location/3875?method=HEAD' |
Response
| Expand | ||
|---|---|---|
| ||
|
An example double check that Synapse's MD5 matches the one in S3 using curl:
| Code Block |
|---|
curl -I -H If-Match:b513a23fc54b7b0d65312e1a900af5a6 'https://s3.amazonaws.com/stagingdata.sagebase.org/3875/0.0.0/mskcc_prostate_cancer.phenotype.zip?Expires=1317918907&AWSAccessKeyId=AKIAJQBSYCAUPIYF5WTA&Signature=UO%2FtfA18HQxed317Nq4YU7ZjPnQ%3D'
HTTP/1.1 200 OK
x-amz-id-2: h3qt9NfdRw7utcyVMCZF/dNRto9ZpmKY56w69HNpuMkNsaDv9MgduGY9L3zBQWl
x-amz-request-id: 3AADDC9EF832ADD2
Date: Tue, 07 Jun 2011 18:40:15 GMT
Last-Modified: Tue, 05 Apr 2011 00:42:50 GMT
ETag: "b513a23fc54b7b0d65312e1a900af5a6"
Accept-Ranges: bytes
Content-Type: application/binary
Content-Length: 30681
Server: AmazonS3 |
Get storage usage
Login required to get the storage usage associated with the current user.
Get aggregated storage usage
Gets aggregated totals over a list of aggregation dimensions. The list of aggregation dimensions are concatenated by comma and assigned to the query parameter 'aggregation'. The list of valid aggregating dimensions are defined in StorageUsageDimension (See Synapse Entity Types). Except for USER_ID and ENTITY_ID, which are reserved for administrators, any combination of aggregations is accepted. The following example aggregates over STORAGE_PROVIDER and CONTENT_TYPE.
Request
| Code Block | ||
|---|---|---|
| ||
curl -i -H sessionToken:<yourSessionToken> -H Accept:application/json https://repo-staging.sagebase.org/repo/v1/storageSummary?aggregation=STORAGE_PROVIDER,CONTENT_TYPE |
Response
| Expand | |||||
|---|---|---|---|---|---|
| |||||
|
Get detailed storage usage
To see details, the following URL fetches the list of storage items for the current user.
Request
| Code Block | ||
|---|---|---|
| ||
curl -i -H sessionToken:<yourSessionToken> -H Accept:application/json https://repo-staging.sagebase.org/repo/v1/storageDetails |
Response
| Expand | |||||
|---|---|---|---|---|---|
| |||||
|
Note that the results are paginated.
Get detailed storage usage for an entity
To see the list of storage items for a particular entity, use the following URL.
Request
| Code Block | ||
|---|---|---|
| ||
curl -i -H sessionToken:<yourSessionToken> -H Accept:application/json https://repo-staging.sagebase.org/repo/v1/storageDetails/entity/<entityID> |
Response
| Expand | ||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||||||
| Code Block | ||||||||||||||||||||||||
|
Get Annotations for a Dataset
Request
|
Response
| Code Block | |
|---|---|
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":[
|
Get the descendants of an entity
Note that the query for descendants is based on secondary indices which are eventually consistent. You may not be able to see the complete list of descendants immediately.
Get all the descendants of an entity
Get all the descendants of an entity. The results are paginated. Use the optional query parameter limit to set the maximum page size. The default page size is 20. To fetch the next page, find the last entity (descendant) on the current page and use its ID to set the query parameter lastEntityId. Here is an example:
| Code Block | ||||
|---|---|---|---|---|
| ||||
curl -i -H sessionToken:<yourToken> -H Accept:application/json 'https://repo.prod.sagebase.org/repo/v1/entity/<entityID>/descendants&limit=2' |
| Code Block | ||||
|---|---|---|---|---|
| ||||
{ "idList": [ { "id": "Cancersyn111" ], }, "Tumor / Tissue Type":[ { "Glioblastoma" "id": "syn112" ], "Species":[ } ] } "Human" ], |
| Code Block | ||||
|---|---|---|---|---|
| ||||
curl -i -H sessionToken:<yourToken> -H Accept:application/json 'https://repo.prod.sagebase.org/repo/v1/entity/<entityID>/descendants?limit=20&lastEntityId=syn112' |
| Code Block | ||||
|---|---|---|---|---|
| ||||
{ "InstitutionidList": [ "TCGA"{ ], "Reference / PubMed ID":[ "18772890"id": "syn113" ] }, "floatAnnotations":{ "Number of Samples":[ 465.0 ] }, "dateAnnotations":{ } } |
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
| Code Block |
|---|
curl -i -H Accept:application/json "http://deflaux-test.appspot.com/repo/v1/dataset?limit=3" |
Response
| Code Block |
|---|
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 { "id": "syn114" }, { "resultsid":[ "syn115" } ] { "name":"Pediatric AML TARGET", "annotations":"/repo/v1/dataset/agxkZWZsYXV4LXRlc3RyFQsSDUdBRUpET0RhdGFzZXQYgvcCDA/annotations", "id":"agxkZWZsYXV4LXRlc3RyFQsSDUdBRUpET0RhdGFzZXQYgvcCDA", } |
Get the descendants of a specific generation
Get all the descendants that are exactly n generations away. The children is generation 1. Children's children are generation 2. So on and so forth. The results are paginated in the same manner. To fetch the next page, find the last entity (descendant) on the current page and use its ID to set the query parameter lastEntityId. Here is an example:
| Code Block | ||||
|---|---|---|---|---|
| ||||
curl -i -H sessionToken:<yourToken> -H Accept:application/json 'https://repo.prod.sagebase.org/repo/v1/entity/<entityID>/descendants/2' |
| Code Block | ||||
|---|---|---|---|---|
| ||||
{ "idList": [ "version":"0.0.1",{ "description":null, "statusid": "In Transitionsyn114", "uri":"/repo/v1/dataset/agxkZWZsYXV4LXRlc3RyFQsSDUdBRUpET0RhdGFzZXQYgvcCDA"}, "etag":"1703131409",{ "creator":"Soheil Meshinchi", "creationDateid":1296182253120, "releaseDate":null, syn115" "layers":[ } ] } |
References
Find reference to any version of an entity
Request
| Code Block |
|---|
curl -i -H {sessionToken:YourSessionToken -H Accept:application/json 'https://repo-staging.sagebase.org/repo/v1/entity/6/referencedby' |
Response
| Expand | ||||||
|---|---|---|---|---|---|---|
| ||||||
|
Find reference to a specific version of an entity
Request
| Code Block |
|---|
curl -i -H sessionToken:YourSessionToken -H "uri":"/datalayer/agxkZWZsYXV4LXRlc3RyEwsSDUdBRUpET0RhdGFzZXQYAQw" Accept:application/json 'https://repo-staging.sagebase.org/repo/v1/entity/6/version/1/referencedby' |
Response
| Expand | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||
|
Schemas
Query Results Schema
The JsonSchema is an emerging standard similar to DTDs for XML.
Request
| Code Block |
|---|
curl -i -H sessionToken:YourSessionToken -H Accept:application/json { "id":"agxkZWZsYXV4LXRlc3RyFQsSDUdBRUpET0RhdGFzZXQYmfIBDA", "type":"G", 'https://repo-staging.sagebase.org/repo/v1/query/schema' |
Response
| Expand | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| |||||||||||
|
Project Schema
The JsonSchema is an emerging standard similar to DTDs for XML.
Request
| Code Block |
|---|
curl -i -H sessionToken:YourSessionToken -H Accept:application/json 'https://repo-staging.sagebase.org/repo/v1/project/schema' |
Response
| Expand | ||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||
|
Eula Schema
The JsonSchema is an emerging standard similar to DTDs for XML.
Request
| Code Block |
|---|
curl -i -H sessionToken:YourSessionToken -H Accept:application/json 'https://repo-staging.sagebase.org/repo/v1/eula/schema' |
Response
| Expand | |||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| |||||||||||||||||||
|
Agreement Schema
The JsonSchema is an emerging standard similar to DTDs for XML.
Request
| Code Block |
|---|
curl -i -H sessionToken:YourSessionToken -H Accept:application/json 'https://repo-staging.sagebase.org/repo/v1/agreement/schema' |
Response
| Expand | ||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||||||
|
Dataset Schema
The JsonSchema is an emerging standard similar to DTDs for XML.
Request
| Code Block |
|---|
curl -i -H sessionToken:YourSessionToken -H Accept:application/json 'https://repo-staging.sagebase.org/repo/v1/dataset/schema' |
Response
| Expand | ||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||
|
Create a Dataset
Request:
| Code Block |
|---|
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
| Code Block |
|---|
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"
}
]
}
|
Add Annotations to a Dataset
First get the empty annotations container for your newly created dataset
Request
| Code Block |
|---|
curl -i http://localhost:8080/repo/v1/dataset/agxkZWZsYXV4LXRlc3RyEwsSDUdBRUpET0RhdGFzZXQYAQw/annotations
|
Response
| Code Block |
|---|
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":{
}
}
|
Request
| Code Block | |
|---|---|
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"]
|
Layer Schema
The JsonSchema is an emerging standard similar to DTDs for XML.
Request
| Code Block |
|---|
curl -i -H sessionToken:YourSessionToken -H Accept:application/json 'https://repo-staging.sagebase.org/repo/v1/layer/schema' |
Response
| Expand | ||
|---|---|---|
| ||
|
Layer Preview Schema
The JsonSchema is an emerging standard similar to DTDs for XML.
Request
| Code Block |
|---|
curl -i -H sessionToken:YourSessionToken -H Accept:application/json 'https://repo-staging.sagebase.org/repo/v1/preview/schema' |
Response
| Expand | |||||||
|---|---|---|---|---|---|---|---|
| |||||||
|
Response
| Code Block | |||||||||
|---|---|---|---|---|---|---|---|---|---|
HTTP/1.1 200 OK
ETag: -1638393853
Content-Type: application/json
Transfer-Encoding: chunked
Server: Jetty(6.1.x)
{
"id":"agxkZWZsYXV4LXRlc3RyEwsSDUdBRUpET0RhdGFzZXQYBww",
|
Dataset or Layer Locations Schema
The JsonSchema is an emerging standard similar to DTDs for XML.
Request
| Code Block |
|---|
curl -i -H sessionToken:YourSessionToken -H Accept:application/json 'https://repo-staging.sagebase.org/repo/v1/location/schema' |
Response
| Expand | |||||
|---|---|---|---|---|---|
| |||||
|
Update a Dataset
Note that the creator and description fields have been changed but all others remain the same.
Request:
| Code Block | ||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
curl -i -H Accept:application/json -H Content-Type:application/json -X PUT -H ETag:1309185941 -d '{
|
Annotations Schema
The JsonSchema is an emerging standard similar to DTDs for XML.
Request
| Code Block |
|---|
curl -i -H sessionToken:YourSessionToken -H Accept:application/json 'https://repo-staging.sagebase.org/repo/v1/annotations/schema' |
Response
| Expand | |||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| |||||||||||||
|
Access Control List Schema
The JsonSchema is an emerging standard similar to DTDs for XML.
Request
| Code Block |
|---|
curl -i ] } ' http://localhost:8080-H sessionToken:YourSessionToken -H Accept:application/json 'https://repo-staging.sagebase.org/repo/v1/dataset/agxkZWZsYXV4LXRlc3RyEwsSDUdBRUpET0RhdGFzZXQYAQw |
...
acl/schema' |
Response
| Expand | ||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||||||||||||||||||||||||||||||
|
Delete a Dataset
Request
| Code Block |
|---|
curl -i -X DELETE http://localhost:8080/repo/v1/dataset/agxkZWZsYXV4LXRlc3RyEwsSDUdBRUpET0RhdGFzZXQYAQw
|
Response
| Code Block | |
|---|---|
HTTP/1.1 204 No Content
Server: Jetty(6.1.x)
|