Page Comparison

...

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 and the where the entity body is passed with a content type of the data we are sending to the service is json

Request

Code Block

curl -i  -H sessionToken:YourSessionToken -H Accept:application/json -H Content-Type:application/json -d '{"name": "SageBioCuration (Wiki Generator 2011_10_05T09_34_38.308_07_00)"}' https://repo-staging.sagebase.org/repo/v1/project

Response

...

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

Code Block

Content-Type: application/json
Date: Wed, 0529 OctAug 20112012 1603:34:4601 GMT
ETag: 0
Location: /repo/v1/projectentity/17334syn1058078
Server: Apache-Coyote/1.1
Content-Length: 334396
Connection: keep-alive
{
{   "accessControlListcreatedOn": "/repo/v1/project/17334/acl"2012-08-29T03:34:00.967Z",
   "annotationsid": "/repo/v1/project/17334/annotations"syn1058078",
   "creationDateparentId":"syn4489",
1317832486238,   "creatormodifiedOn": "nicole.deflaux@sagebase.org","2012-08-29T03:34:00.967Z",
   "descriptioncreatedBy":"John nullHill",
   "etagaccessControlList": "0"/repo/v1/entity/syn1058078/acl",
   "idetag": "173340",
   "namemodifiedBy": "SageBioCuration (Wiki Generator 2011_10_05T09_34_38.308_07_00)",John Hill",
   "parentIdname": "3728syn1058078",
   "uriannotations": "/repo/v1/entity/projectsyn1058078/17334annotations"
}

Create a new End-User Licence Agreement

Create a new End-User License Agreement to specify the terms of use for a dataset and how the dataset should be cited.

Request

Code Block

curl -i  -H sessionToken:YourSessionToken -H Accept:application/json -H Content-Type:application/json -d '{,
   "agreemententityType": "<p><b><larger>Copyright 2011 Sage Bionetworks<\/larger><\/b><br/><br/><\/p><p>Licensed under the Apache License, Version 2.0 ..."org.sagebionetworks.repo.model.Project",
   "nameuri": "SageBioCurationEula (Wiki Generator 2011_10_05T09_34_38.308_07_00)"
}' https://repo-staging.sagebase.org/repo/v1/eula

Response

Code Block

HTTP/1.1 201 Created
Content-Type: application/json
Date: Wed, 05 Oct 2011 16:34:46 GMT
ETag: 0
Location: /repo/v1/eula/17335
Server: Apache-Coyote/1.1
transfer-encoding: chunked
Connection: keep-alive

{
  "accessControlList": "/repo/v1/eula/17335/acl",
  "agreement": "<p><b><larger>Copyright 2011 Sage Bionetworks<\/larger><\/b><br/><br/><\/p><p>Licensed under the Apache License, Version 2.0 ...",
  "annotations": "/repo/v1/eula/17335/annotations",
  "creationDate": 1317832486505,
  "etag": "0",
  "id": "17335",
  "name": "SageBioCurationEula (Wiki Generator 2011_10_05T09_34_38.308_07_00)",
  "parentId": "3730",
  "uri": "/repo/v1/eula/17335"
}

Create a Dataset

Note that the id of the End-User License Agreement we just created is passed as the value of eulaId for the dataset so that the End-User License Agreement is bound to the dataset

Request

Code Block

curl -i  -H sessionToken:YourSessionToken -H Accept:application/json -H Content-Type:application/json -d '{
  "creator": "Charles Sawyers",
  "description": "Genetic and epigenetic alterations have been identified that ...",
  "eulaId": "17335",
  "name": "MSKCC Prostate Cancer",
  "parentId": "17334",
  "releaseDate": "2008-09-14",
  "status": "Pending",
  "version": "1.0.0"
}' https://repo-staging.sagebase.org/repo/v1/dataset

Response

Code Block

HTTP/1.1 201 Created
Content-Type: application/json
Date: Wed, 05 Oct 2011 16:34:46 GMT
ETag: 0
Location: /repo/v1/dataset/17336
Server: Apache-Coyote/1.1
Content-Length: 585
Connection: keep-alive

{
  "accessControlList": "/repo/v1/dataset/17336/acl",
  "annotations": "/repo/v1/dataset/17336/annotations",
  "creationDate": 1317832486693,
  "creator": "Charles Sawyers",
  "description": "Genetic and epigenetic alterations have been identified that ...",
  "etag": "0",
  "eulaId": "17335",
  "hasClinicalData": false,
  "hasExpressionData": false,
  "hasGeneticData": false,
  "id": "17336",
  "layers": "/repo/v1/dataset/17336/layer",
  "locations": "/repo/v1/dataset/17336/location",
  "name": "MSKCC Prostate Cancer",
  "parentId": "17334",
  "releaseDate": 1221350400000,
  "status": "Pending",
  "uri": "/repo/v1/dataset/17336",
  "version": "1.0.0"
}

Update a Dataset

...

"/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
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 the change in the URI to include the id of the dataset we wish to update and the ETag header using the value previously returnedis 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:YourSessionTokenXXXXXXXXXXXXX -H ETag:0 -H Accept:application/json -H Content-Type:application/json -X PUT -d '{
   "accessControlListcreatedOn": "/repo/v1/dataset/17336/acl","2012-08-29T03:34:00.967Z",
   "annotationsid": "/repo/v1/dataset/17336/annotations",
  "creationDate": 1317832486693,"syn1058078",
   "creatorparentId": "Charles Sawyerssyn4489",
   "descriptionmodifiedOn": "Genetic and epigenetic alterations have been identified that ...","2012-08-29T03:34:00.967Z",
   "etagcreatedBy":"John "0Hill",
   "eulaIdaccessControlList": "17335"/repo/v1/entity/syn1058078/acl",
   "hasClinicalDataetag": false,
  "hasExpressionData": false,"0",
   "hasGeneticDatamodifiedBy": false,
  "id": "17336"John Hill",
   "layersname": "/repo/v1/dataset/17336/layer"Example Project",
   "locationsannotations": "/repo/v1/datasetentity/17336syn1058078/locationannotations",
  "name": "MSKCC Prostate Cancer",
  "parentIdentityType": "17334",
  "releaseDate": 1221350400000,
  "status": "Current","org.sagebionetworks.repo.model.Project",
   "uri": "/repo/v1/dataset/17336",
  "version": "1.0.0v1/entity/syn1058078"
}' https://repo-stagingprod.sagebase.org/repo/v1/datasetentity/17336syn1058078

Response

Code Block

HTTP/1.1 200 OK
Content-Type: application/json
Date: Wed, 0529 OctAug 20112012 04:16:34:4618 GMT
ETag: 1
Server: Apache-Coyote/1.1
transferContent-encodingLength: chunked401
Connection: keep-alive
{
{   "accessControlListcreatedOn": "/repo/v1/dataset/17336/acl"2012-08-29T03:34:00.967Z",
   "annotationsid": "/repo/v1/dataset/17336/annotations"syn1058078",
  "creationDate": 1317832486693,
  "creatorparentId": "Charles Sawyerssyn4489",
   "descriptionmodifiedOn": "Genetic and epigenetic alterations have been identified that ..."2012-08-29T04:16:18.234Z",
   "etagcreatedBy":"John Hill"1",
   "eulaIdaccessControlList": "17335"/repo/v1/entity/syn1058078/acl",
   "hasClinicalDataetag": false,
  "hasExpressionData": false,"1",
   "hasGeneticDatamodifiedBy": false,
  "id": "17336""John Hill",
   "layersname": "/repo/v1/dataset/17336/layer"Example Project",
   "locationsannotations": "/repo/v1/datasetentity/17336syn1058078/locationannotations",
 
"name": "MSKCC Prostate Cancer",
  "parentId"entityType": "17334",
  "releaseDate": 1221350400000"org.sagebionetworks.repo.model.Project",
  "status": "Current",
  "uri": "/repo/v1/dataset/17336",
  "version": "1.0.0entity/syn1058078"
}

Add Annotations to a Dataset

...

Versions Compared

Old Version 59

New Version 60

Key

Create a

Entity

Create a new End-User Licence Agreement

Create a Dataset

Update a Dataset

Basic Entity Fields

Update an Entity

Add Annotations to a Dataset