| Table of Contents |
|---|
Entity Types
...
In this example, we can see that Link implements Entity and adds two property that are specific to Links: 'linkTo' and 'linkToClassName'. The links to the actual JSON for each entity schema can be found in the table below. The full list of the current Entities registered in Synapse can be founds int the following file: Register.json. We will cover more on the register in the next section. For an API developer the following summary table contains the most important information about each entity:
Get Entity Registry
The following curl commands show how to fetch the current Registry from Synapse:
...
| Code Block |
|---|
$ curl -i -H Accept:application/json 'https://repo-prod.sagebase.org/repo/v1/entity/registry' |
Response
| Code Block |
|---|
HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
Content-Type: application/json
Transfer-Encoding: chunked
Date: Fri, 01 Jun 2012 23:16:11 GMT
{
"entityTypes":[
{
"validParentTypes":[
"org.sagebionetworks.repo.model.Project"
],
"name":"dataset",
"defaultParentPath":"/root",
"entityType":"org.sagebionetworks.repo.model.Study",
"aliases":[
"dataset",
"study"
]
},
{
"validParentTypes":[
"org.sagebionetworks.repo.model.Study",
"org.sagebionetworks.repo.model.Project"
],
"name":"layer",
"defaultParentPath":"/root",
"entityType":"org.sagebionetworks.repo.model.Data",
"aliases":[
"layer",
"data"
]
},
{
"validParentTypes":[
"org.sagebionetworks.repo.model.Folder",
"org.sagebionetworks.repo.model.Project",
"DEFAULT"
],
"name":"project",
"defaultParentPath":"/root",
"entityType":"org.sagebionetworks.repo.model.Project"
},
{
"validParentTypes":[
"org.sagebionetworks.repo.model.Data"
],
"name":"preview",
"defaultParentPath":"/root",
"entityType":"org.sagebionetworks.repo.model.Preview"
},
{
"validParentTypes":[
"DEFAULT",
"org.sagebionetworks.repo.model.Folder"
],
"name":"folder",
"defaultParentPath":"/root",
"entityType":"org.sagebionetworks.repo.model.Folder"
},
{
"validParentTypes":[
"org.sagebionetworks.repo.model.Project"
],
"name":"analysis",
"defaultParentPath":"/root",
"entityType":"org.sagebionetworks.repo.model.Analysis"
},
{
"validParentTypes":[
"org.sagebionetworks.repo.model.Folder",
"org.sagebionetworks.repo.model.Analysis",
"DEFAULT"
],
"name":"step",
"defaultParentPath":"/root",
"entityType":"org.sagebionetworks.repo.model.Step"
},
{
"validParentTypes":[
"org.sagebionetworks.repo.model.Project"
],
"name":"code",
"defaultParentPath":"/root",
"entityType":"org.sagebionetworks.repo.model.Code"
},
{
"validParentTypes":[
"org.sagebionetworks.repo.model.Project",
"org.sagebionetworks.repo.model.Folder",
"org.sagebionetworks.repo.model.Study",
"org.sagebionetworks.repo.model.Data",
"org.sagebionetworks.repo.model.Step",
"org.sagebionetworks.repo.model.Analysis",
"DEFAULT"
],
"name":"link",
"defaultParentPath":"/root",
"entityType":"org.sagebionetworks.repo.model.Link"
},
{
"validParentTypes":[
"org.sagebionetworks.repo.model.Project",
"org.sagebionetworks.repo.model.Study"
],
"name":"phenotypedata",
"defaultParentPath":"/root",
"entityType":"org.sagebionetworks.repo.model.PhenotypeData",
"aliases":[
"phenotypedata",
"layer"
]
},
{
"validParentTypes":[
"org.sagebionetworks.repo.model.Project",
"org.sagebionetworks.repo.model.Study"
],
"name":"genotypedata",
"defaultParentPath":"/root",
"entityType":"org.sagebionetworks.repo.model.GenotypeData",
"aliases":[
"genotypedata",
"layer"
]
},
{
"validParentTypes":[
"org.sagebionetworks.repo.model.Project",
"org.sagebionetworks.repo.model.Study"
],
"name":"expressiondata",
"defaultParentPath":"/root",
"entityType":"org.sagebionetworks.repo.model.ExpressionData",
"aliases":[
"expressiondata",
"layer"
]
},
{
"validParentTypes":[
"org.sagebionetworks.repo.model.Project",
"org.sagebionetworks.repo.model.Study"
],
"name":"robject",
"defaultParentPath":"/root",
"entityType":"org.sagebionetworks.repo.model.RObject"
}
]
} |
Get Full Entity Schema
...
The "entityType" can be used like any REST Resource ID to get the full schema for an Entity. The following example shows how to get the full schema of a Study:
Request
| Code Block |
|---|
curl -i -H Accept:application/json 'https://repo-prod.sagebase.org/repo/v1/REST/resources/schema?resourceId='org.sagebionetworks.repo.model.Study'' |
Response
| Code Block |
|---|
HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
Content-Type: application/json
Transfer-Encoding: chunked
Date: Fri, 01 Jun 2012 23:27:36 GMT
{
"title":"Study",
"description":"JSON schema for Study POJO",
"implements":[
{
"$ref":"org.sagebionetworks.repo.model.Locationable"
}
],
"properties":{
"platform":{
"title":"Platform",
"description":"Chip platform for the samples in this Study. Platform is described by the Synapse ontology concept: http://synapse.sagebase.org/ontology#12591",
"links":[
{
"rel":"describedby",
"href":"http://synapse.sagebase.org/ontology#12591"
}
],
"type":"string"
},
"species":{
"title":"Species",
"description":"The species associated with this Study",
"type":"string"
},
"tissueType":{
"title":"Tissue Type",
"description":"Type of tissue for the samples in this Data. Tissue is described by the Synapse ontology concept: http://synapse.sagebase.org/ontology#11171",
"links":[
{
"rel":"describedby",
"href":"http://synapse.sagebase.org/ontology#11171"
}
],
"type":"string"
},
"numSamples":{
"title":"Number of samples",
"description":"Approximate number of samples in this Study",
"type":"integer"
},
"disease":{
"title":"Disease",
"description":"The disease associated with this Study",
"type":"string"
}
}
} |
Get Effective Entity Schema
The full schema is useful to see the full schema hierarchy of an Entity. However, if you just need to know what the properties of an Entity are, then it can be tedious to build up this list by navigating the type hierarchy. To get around this problem, the REST API provides an "Effective" schema for any REST Resource. The effective schema is the schema of a resources with all type hierarchy collapsed. For example, here is how to get the effective schema from the REST API:
Request
| Code Block |
|---|
curl -i -H Accept:application/json 'https://repo-prod.sagebase.org/repo/v1/REST/resources/effectiveSchema?resourceId='org.sagebionetworks.repo.model.Study'' |
Response
| Code Block |
|---|
HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
Content-Type: application/json
Transfer-Encoding: chunked
Date: Fri, 01 Jun 2012 23:35:04 GMT
{
"id":"org.sagebionetworks.repo.model.Study",
"title":"Study",
"description":"JSON schema for Study POJO",
"name":"Study",
"properties":{
"accessControlList":{
"description":"The URI to get to this entity's access control list",
"transient":true,
"type":"string"
},
"etag":{
"description":"Synapse employs an Optimistic Concurrency Control (OCC) scheme to handle concurrent updates. Since the E-Tag changes every time an entity is updated it is used to detect when a client's current representation of an entity is out-of-date.",
"transient":true,
"type":"string"
},
"versionLabel":{
"title":"Version",
"description":"The version label for this entity",
"type":"string"
},
"modifiedBy":{
"title":"Modified By",
"description":"The user that last modified this entity.",
"transient":true,
"type":"string"
},
"contentType":{
"description":"The type of file of this location",
"type":"string"
},
"disease":{
"title":"Disease",
"description":"The disease associated with this Study",
"type":"string"
},
"entityType":{
"description":"The full class name of this entiy.",
"transient":true,
"type":"string"
},
"id":{
"description":"The unique immutable ID for this entity. A new ID will be generated for new Entities. Once issued, this ID is guaranteed to never change or be re-issued",
"transient":true,
"type":"string"
},
"parentId":{
"description":"The ID of the parent of this entity",
"type":"string"
},
"versionComment":{
"title":"Version Comment",
"description":"The version comment for this entity",
"type":"string"
},
"locations":{
"items":{
"id":"org.sagebionetworks.repo.model.LocationData",
"description":"JSON schema for Location Data POJO",
"name":"LocationData",
"properties":{
"path":{
"description":"The path of this location",
"type":"string"
},
"type":{
"id":"org.sagebionetworks.repo.model.LocationTypeNames",
"description":"The type of this location",
"name":"LocationTypeNames",
"enum":[
"awss3",
"awsebs",
"sage",
"external",
"github"
],
"type":"string"
}
},
"type":"object"
},
"description":"The list of location data.",
"contentEncoding":"binary",
"uniqueItems":false,
"type":"array"
},
"tissueType":{
"title":"Tissue Type",
"description":"Type of tissue for the samples in this Data. Tissue is described by the Synapse ontology concept: http://synapse.sagebase.org/ontology#11171",
"links":[
{
"rel":"describedby",
"href":"http://synapse.sagebase.org/ontology#11171"
}
],
"type":"string"
},
"description":{
"title":"Description",
"description":"The description of this entity.",
"type":"string"
},
"name":{
"title":"Name",
"description":"The name of this entity",
"type":"string"
},
"attachments":{
"items":{
"id":"org.sagebionetworks.repo.model.attachment.AttachmentData",
"description":"JSON Data about a single attachment.",
"name":"AttachmentData",
"properties":{
"previewId":{
"description":"This token is used to get a pre-signed URL that can be used to download this attachment's preview.",
"type":"string"
},
"tokenId":{
"description":"This token is used to get a pre-signed URL that can be used to download this attachment.",
"type":"string"
},
"name":{
"description":"The name of this attachment.",
"type":"string"
},
"md5":{
"type":"string"
},
"contentType":{
"type":"string"
},
"url":{
"description":"When provided, the URL can be used to directly download this attachment.",
"type":"string"
},
"previewState":{
"id":"org.sagebionetworks.repo.model.attachment.PreviewState",
"description":"The state of the preview for this attachment",
"name":"PreviewState",
"enum":[
"FAILED",
"PREVIEW_EXISTS",
"NOT_COMPATIBLE"
],
"type":"string"
}
},
"type":"object"
},
"description":"The list of attachment data.",
"contentEncoding":"binary",
"uniqueItems":false,
"type":"array"
},
"platform":{
"title":"Platform",
"description":"Chip platform for the samples in this Study. Platform is described by the Synapse ontology concept: http://synapse.sagebase.org/ontology#12591",
"links":[
{
"rel":"describedby",
"href":"http://synapse.sagebase.org/ontology#12591"
}
],
"type":"string"
},
"s3Token":{
"description":"The URL to an S3 token for this entity. This URL is provided by Synapse.",
"type":"string"
},
"species":{
"title":"Species",
"description":"The species associated with this Study",
"type":"string"
},
"versionUrl":{
"description":"The full URL of this exect version. This URL is provided by Synapse.",
"transient":true,
"type":"string"
},
"uri":{
"description":"The Uniform Resource Identifier (URI) for this entity.",
"transient":true,
"type":"string"
},
"createdOn":{
"title":"Created On",
"description":"The date this entity was created.",
"transient":true,
"format":"date-time",
"type":"string"
},
"modifiedOn":{
"title":"Modified On",
"description":"The date this entity was last modified.",
"transient":true,
"format":"date-time",
"type":"string"
},
"versions":{
"description":"The URL to get all versions of this entity. This URL is provided by Synapse.",
"transient":true,
"type":"string"
},
"createdBy":{
"title":"Created By",
"description":"The user that created this entity.",
"transient":true,
"type":"string"
},
"md5":{
"description":"The checksum of this location",
"type":"string"
},
"numSamples":{
"title":"Number of samples",
"description":"Approximate number of samples in this Study",
"type":"integer"
},
"annotations":{
"description":"The URI to get to this entity's annotations",
"transient":true,
"type":"string"
},
"versionNumber":{
"title":"Version Number",
"description":"The version number issued to this version on the entity.",
"transient":true,
"type":"integer"
}
},
"type":"object"
}
|
Get All REST Resources
All REST Resources supported by the Synapse REST API, have a JSON schema and a ResourceID. The full list of REST Resources ID can be fetched with the following command:
Request
| Code Block |
|---|
curl -i -H Accept:application/json 'https://repo-prod.sagebase.org/repo/v1/REST/resources' |
Response
| Code Block |
|---|
HTTP/1.1 200 OK Server: Apache-Coyote/1.1 Content-Type: application/json Transfer-Encoding: chunked Date: Fri, 01 Jun 2012 23:42:41 GMT { "list":[ "org.sagebionetworks.repo.model.EntityHeader", "org.sagebionetworks.repo.model.attachment.AttachmentData", "org.sagebionetworks.repo.model.Study", "org.sagebionetworks.repo.model.ExpressionData", "org.sagebionetworks.repo.model.Analysis", "org.sagebionetworks.repo.model.daemon.BackupSubmission", "org.sagebionetworks.repo.model.Data", "org.sagebionetworks.repo.model.Link", "org.sagebionetworks.repo.model.S3Token", "org.sagebionetworks.repo.model.attachment.S3AttachmentToken", "org.sagebionetworks.repo.model.ontology.ConceptRequest", "org.sagebionetworks.repo.model.EnvironmentDescriptor", "org.sagebionetworks.repo.model.ResourceAccess", "org.sagebionetworks.repo.model.AccessControlList", "org.sagebionetworks.repo.model.Preview", "org.sagebionetworks.repo.model.DatasetTrackingData", "org.sagebionetworks.repo.model.AcquisitionTrackingData", "org.sagebionetworks.repo.model.attachment.PresignedUrl", "org.sagebionetworks.repo.model.search.Facet", "org.sagebionetworks.repo.model.registry.MigrationSpec", "org.sagebionetworks.repo.model.registry.FieldDescription", "org.sagebionetworks.repo.model.Media", "org.sagebionetworks.repo.model.ontology.Concept", "org.sagebionetworks.repo.model.auth.UserEntityPermissions", "org.sagebionetworks.repo.model.search.query.FacetSort", "org.sagebionetworks.repo.model.Project", "org.sagebionetworks.repo.model.Folder", "org.sagebionetworks.repo.model.search.query.KeyValue", "org.sagebionetworks.repo.model.search.query.KeyList", "org.sagebionetworks.repo.model.search.DocumentFields", "org.sagebionetworks.repo.model.PhenotypeData", "org.sagebionetworks.repo.model.RObject", "org.sagebionetworks.repo.model.ontology.ConceptSummary", "org.sagebionetworks.repo.model.status.StackStatus", "org.sagebionetworks.repo.model.CurationTrackingData", "org.sagebionetworks.repo.model.search.FacetConstraint", "org.sagebionetworks.repo.model.registry.EntityMigration", "org.sagebionetworks.repo.model.Reference", "org.sagebionetworks.repo.model.Row", "org.sagebionetworks.repo.model.LocationData", "org.sagebionetworks.repo.model.GenotypeData", "org.sagebionetworks.repo.model.StatusHistoryRecord", "org.sagebionetworks.repo.model.registry.FieldMigrationSpec", "org.sagebionetworks.repo.model.Code", "org.sagebionetworks.repo.model.search.SearchResults", "org.sagebionetworks.repo.model.ExampleEntity", "org.sagebionetworks.repo.model.registry.RenameData", "org.sagebionetworks.repo.model.ontology.ConceptResponsePage", "org.sagebionetworks.repo.model.search.Document", "org.sagebionetworks.repo.model.ontology.SummaryRequest", "org.sagebionetworks.repo.model.daemon.RestoreSubmission", "org.sagebionetworks.repo.model.UserProfile", "org.sagebionetworks.repo.model.Step", "org.sagebionetworks.repo.model.RestResourceList", "org.sagebionetworks.repo.model.UserGroup", "org.sagebionetworks.repo.model.EntityPath", "org.sagebionetworks.repo.model.registry.EntityRegistry", "org.sagebionetworks.repo.model.daemon.BackupRestoreStatus", "org.sagebionetworks.repo.model.registry.EntityTypeMetadata", "org.sagebionetworks.repo.model. |
...
search.query.SearchQuery", "org.sagebionetworks.repo.model. |
...
search.Hit", "org.sagebionetworks.repo.model. |
...
attachment.UploadResult", "org.sagebionetworks.repo.model. |
...
registry.EntityTypeMigrationSpec", "org.sagebionetworks.repo.model.search. |
...
query.FacetTopN", "org.sagebionetworks.repo.model. |
...
org.sagebionetworks.repo.model.Link...
...
search.DocumentBatch"
]
}
|
Just like Entities, the full schema and effective schema can be fetched using the resulting Resource ID for any REST Resource.
Entity Type Registration
Register.json
...
| Register field | Description |
|---|---|
validParentTypes | Lists other Entity types that are considered valid parent of a given entity |
aliases | The list of extra valid values that can be used to query for an Entity. For example, 'dataset' is an alias for 'study'. This means a Synapse query to find all studies can be written as 'select * from dataset' or 'select * from study'. By default, any type that an Entity extends is automatically used as an alias. For example, since all Entity types extend 'Entity', they all have an implied alias of 'entity'. So a query of 'select * from entity' will return all Entities in Synapse regardless of type. |
name | The basic name of this entity. This name must be unique within Synapse. |
entityType | When creating a new Entity instance through the REST API, the caller must provide the 'entityType' field to tell Synapse the Entity type they wish to create. The 'entityType' field value must always match the full class name of the entity. |
defaultParentPath | This field tells Synapse where to place a new instance of this Entity type when the caller does not specify a 'parentId'. All Entity instances will have a parent in Synapse (with the only exception being the 'root' entity). |
Entity type REST API
...
| . |
...
Creating and Updating Entity Types
...