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	POST	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.
/{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

Finally List Versions Again

...

Versions Compared

Old Version 71

New Version 72

Key

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

Version API Examples:

Get the Location to Version

Promote a Version

Finally List Versions Again