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.

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. 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

Response

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:

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

Response

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:

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

Response

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

Response

Entity Annotations

Get Annotations

First get the current annotations for your newly created data entity.

Request

Response

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

Response

Set Entity Location

In this example we will be uploading a simple text file with the following content:

We will need to know the md5 of our file before we start.  For this example the text the MD5 is:

There are three steps required to set an Entity's location data:

1. Create an S3 Token.  We will use this token to upload the file to Amazon's S3.

   1. Request

      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/s3Token

      Response

2. 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

   1. Request
      
      

      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

3. Once the file has been successfully uploaded to S3 update the Entity using the S3 Token:

   1. Request

      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/syn1151499

      Response

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:

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.

Current API

The following table describes how versioning effects the current entity CRUD API:

Version-able Additions to the API

The following table describes the new methods for manipulating the versions of a version-able entity.

Version API Examples:

Get the Location to Version

Get the location object we created earlier:

Request

Response

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

Response

List Versions

List all of the version of this location. The current version will be the first in the list:

Request

Response

Get a Previous Version

To get a previous version we must provide the version number we would like to fetch:

Request

Response

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

Response

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

Response

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

Response

Finally List Versions Again

List all of the version of this location. Since we deleted the first version, only the second remains:

Request

Response

Delete a Project