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