/
Repository Service API

Repository Service API

Sept 26, 2014

Introduction

The Query API is loosely modeled after Facebook's Query Language.

The REST API took inspiration from several successful REST APIs:

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

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

HTTP/1.1 201 Created Content-Type: application/json Date: Tue, 28 Aug 2012 23:03:04 GMT Server: Apache-Coyote/1.1 Content-Length: 43 Connection: keep-alive { "sessionToken":"XXXXXXXXXXXXXXX" }

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

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

Content-Type: application/json Date: Wed, 29 Aug 2012 03:34:01 GMT ETag: 0 Location: /repo/v1/entity/syn1058078 Server: Apache-Coyote/1.1 Content-Length: 396 Connection: keep-alive { "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":"syn1058078", "annotations":"/repo/v1/entity/syn1058078/annotations", "entityType":"org.sagebionetworks.repo.model.Project", "uri":"/repo/v1/entity/syn1058078" }

 

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