Page Comparison

...

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

Response

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

Response

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:

...

URL	HTTP Type	Description
/{versionable-entityType}/{entityId}/version	POSTPUT	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

...

Expand

title	[Click to show]

Code Block
HTTP/1.1 204 No Content Content-length: 0 Content-Type: text/plain; charset=UTF-8 Date: Wed, 05 Oct 2011 16:34:51 GMT Server: Apache-Coyote/1.1 Connection: keep-alive

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

Code Block
TODO!!!!

Finally List Versions Again

...

Currently supported data types:

layer

<data type>
dataset

project
folder
code
phenotypedata
genotypedata
expressiondata
robject
summary
genomicdata 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'

...

Code Block
SELECT * FROM layer WHERE layer.parentId == <parentId> [LIMIT <#>] [OFFSET <#>]

...

Code Block
SELECT * FROM layer WHERE layer.parentId == <parentId> ORDER BY <field name> [ASC\|DESC] [LIMIT <#>] [OFFSET <#>]

...

To see details, the following URL fetches the list of storage items for the current user.

Request

Code Block

language	bash

curl -i -H sessionToken:<yourSessionToken> -H Accept:application/json https://repo-staging.sagebase.org/repo/v1/storageDetails

...

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

language	bash

curl -i -H sessionToken:<yourSessionToken> -H Accept:application/json https://repo-staging.sagebase.org/repo/v1/storageDetails/entity/<entityID>

Response

Expand

title	[Click to show]

Code Block

language	bash

{
    "paging": {
        "previous": "/repo/v1/storageDetails?offset=1&limit=100"
    }, 
    "results": [
        {
            "contentMd5": "2f1f4348a5452110ad9490609dd4dcb8", 
            "contentSize": 29129, 
            "contentType": "image/png", 
            "id": "134053", 
            "isAttachment": true, 
            "location": "/1439206/1439207/Austria.png", 
            "nodeId": "syn1439206", 
            "storageProvider": "awss3", 
            "userId": "1439205"
        }, 
        {
            "contentMd5": "27faaf994136363f2885bd9acb1a4472", 
            "contentSize": 26169, 
            "contentType": "image/png", 
            "id": "134054", 
            "isAttachment": true, 
            "location": "/1439206/1439209/Switzerland.png", 
            "nodeId": "syn1439206", 
            "storageProvider": "awss3", 
            "userId": "1439205"
        }, 
        {
            "contentMd5": "7d96b9ebe9bb283b33bf6ff143cd4ab7", 
            "contentSize": 14330, 
            "contentType": "application/pdf", 
            "id": "134055", 
            "isAttachment": true, 
            "location": "/1439206/1439214/Trees-In-MangoDB.pdf", 
            "nodeId": "syn1439206", 
            "storageProvider": "awss3", 
            "userId": "1439205"
        },
    ], 
    "totalNumberOfResults": 3
}

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

language	bash
title	Request for getting the first page

curl -i -H sessionToken:<yourToken> -H Accept:application/json 'https://repo.prod.sagebase.org/repo/v1/entity/<entityID>/descendants&limit=2'

Code Block

language	bash
title	Response for getting the first page

{
    "idList": [
        {
            "id": "syn111"
        }, 
        {
            "id": "syn112"
        }
    ]
}

Code Block

language	bash
title	Request for getting the second page

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

language	bash
title	Response for getting the second page

{
    "idList": [
        {
            "id": "syn113"
        }, 
        {
            "id": "syn114"
        }, 
        {
            "id": "syn115"
        }
    ]
}

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

language	bash
title	Request for getting the descendants of the 2nd generation

curl -i -H sessionToken:<yourToken> -H Accept:application/json 'https://repo.prod.sagebase.org/repo/v1/entity/<entityID>/descendants/2'

Code Block

language	bash
title	Response for getting the descendants of the 2nd generation

{
    "idList": [
        {
            "id": "syn114"
        }, 
        {
            "id": "syn115"
        }
    ]
}

References

Find reference to any version of an entity

...

Versions Compared

Old Version 70

New Version Current

Key

Versions Create/Read/Update/Delete (and Promote)

Version API Examples:

Get the Location to Version

Promote a Version

Finally List Versions Again

Get detailed storage usage for an entity

Get the descendants of an entity

Get all the descendants of an entity

Get the descendants of a specific generation

References

Find reference to any version of an entity