...
We conceptual divide the client commands into three levels (1) BasicCommon functions, (2) Power User Advanced functions and (3) low-level Web API functions.
...
The first collection of commands captures the majority of functionality of interest to users. The second collection rounds out the functionality with less frequently used functions. The third set comprises simple, low level wrappers around the Synapse web service interface. By including this third set users can access web services in advance of having specialized commands in the analytic clients.
| Command | comments | R Syntax | Python Syntax | Command Line Syntax | |||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| 1 – Common functions | |||||||||||
| Create a Synapse file handle in memory, specifying the path to the file in the local file system, the name in Synapse, and the Folder in Synapse. This step 'stages' a file to be sent to Synapse. Additional parameters (...) are interpreted as properties or annotations, in the manner of synSet(), defined below. If 'name' is omitted, it defaults to the file's name. If 'synapseStore' is TRUE then file is uploaded to S3, else only the file location is saved. | The specified file doesn't move or get copied. | File(path="/path/to/file", synapseStore=T, name="foo", parentId="syn101", ...) | File(path="/path/to/file", synapseStore=T, name="foo", parentId="syn101", **kwargs) | NA | |||||||
| Create a Synapse file handle in memory which will be a serialized version of an in-memory object. Additional parameters (...) are interpreted as properties or annotations, in the manner of synSet(), defined below. If 'synapseStore' is TRUE then file is uploaded to S3, else only the file location is saved. | The object is not serialized at this time. (We are hoping people will like calling the object a File, even though it takes an in-memory object as a parameter.) | File(obj=<obj ref>, synapseStore=T, name="foo", parentId="syn101", ...) | Will not be implemented in python. | NA | |||||||
| Create a Synapse Record in memory, specifying the name and the Folder in Synapse. This step 'stages' a Record to be sent to Synapse. Additional parameters (...) are interpreted as properties or annotations, in the manner of synSet(), defined below.
| Files aren't moved or copied. TODO: How do you specify file annotations (as distinct from Strings)? Shall we introduce in-memory wrappers around files and urls to help distinguish them? | Record(name="foo", parentId="syn101", ...) | Record(name="foo", parentId="syn101", **kwargs) | ||||||||
| Create a Folder or Project in memory. Name and parentId are optional. | Folder(name="foo", parentId="syn101", ...) Project(name="foo", ...) | Folder(name="foo", parentId="syn101", **kwargs) Project(name="foo", **kwargs) | |||||||||
| Set an entity's attribute (property or annotation) in memory. Client first checks properties, then goes to annotations; (setting to NULL deletes it in R, using DEL operator in python deletes it) | TODO: we want to include files and (for R) in memory objects | synAnnot(entity, name)<-value | entity.parentId="syn101" | ||||||||
| Gets an entity's attribute value (property or annotation) from the object already in memory. | synAnnot(entity, name); returns NULL if undefined | entity.name; throws exception if value is undefined | |||||||||
| Create or update an entity (File, Folder, etc.) in Synapse. May also specify (1) whether a name collision in an attempted 'create' should become an 'update', (2) whether to 'force' a new version to be created, (3) the list of entities 'used' to generate this one, (4) the list of entities 'executed' to generate this one, (5) the name of the generation activity, and (6) the description of the generation activity. | TODO: Give some examples. | synStore(entity, used, executed, activityName=NULL, activityDescription=NULL, createOrUpdate=T, forceVersion=T) | synStore(entity, used, executed, activityName=None, activityDescription=None, createOrUpdate=T, forceVersion=T) | synapse create --name NAME --parentid PARENTID --description DESCRIPTION --type TYPE --file PATH --update=T/F --forceVersion=T/F | |||||||
| Get an entity (file, folder, etc.) from the Synapse server, with its attributes (properties, annotations) and, optionally, with its associated file(s). if.collision is one of "keep.both", "keep.original", or "overwrite.original", telling the system what to do if a different file is found at the given local file location. | 'download' and 'load' are ignored for objects lacking Files. OK for download=F and load=T, this means don't cache (a valid choice if the File lives on a network share). If a downloadLocation is not provided a default, read-only cache location is used. If a downloadLocation IS provided, then the client must handle collisions with existing files. Note, 'downloadLocation' must be a folder, i.e. it cannot be used to rename files. | synGet(id, version, downloadFile=T, downloadLocation=NULL, ifcollision="keep.both", load=T) | synapse.get(id, version, downloadFile=True, downloadLocation=None, ifcollision="keep.both", load=True) | synapse get ID -v NUMBER | |||||||
| Trash an entity, and all of its children (move all Folders and Files within a Folder to the trash can). | synTrash(id) / synTrash(entity) | synapse.trash() | synapse trash id | ||||||||
| Open the web browser to the page for this entity. | onWeb(entityId) / onWeb(entity) | onweb(entityId) / onweb(entity) | synapse onweb id | ||||||||
| log-in | get API key and write to user's properties file | synapseLogin(<user>,<pw>) | synapseLogin(<user>,<pw>) | NA | |||||||
| log-out | delete API key from properties file | synapseLogout() | synapseLogout() | NA | |||||||
| 2 – Power User Level | |||||||||||
| Execute query | TODO: pagination, e.g. the function returns an iterator. Look at current implementation in R client. | synQuery(queryString) | synapse.query(queryString) | ||||||||
| we talked about this, but is it needed? | |||||||||||
| we talked about this, but is it needed? | |||||||||||
| Retrieve the wiki for an entity | TODO: Is it a requirement that we retrieve attachments? If not, do we retrieve file handles? Is this the id of the wiki or the wiki? | synGetWiki(id, version) / synGetWiki(entity) | synapse.getWiki(id, version) synapse.getWiki(entity) | ||||||||
| synStoreWiki() | synapse.storeWiki() | ||||||||||
| synGetAnnotations() | |||||||||||
| synSetAnnotations() | |||||||||||
| synGetProperties() | |||||||||||
| Access properties, throwing exception if property is not defined. | synSetProperties() | ||||||||||
| synGetAnnotation() | |||||||||||
| synSetAnnotation() | |||||||||||
| Access property, throwing exception if property is not defined. | synGetProperty() | ||||||||||
| Access property, throwing exception if property is not defined. Setting to NULL deletes. | synSetProperty() | ||||||||||
| Create an Activity (provenance object) in memory. | Activity(name, description, used, executed) | ||||||||||
| Create or update the Activity in Synapse | synStoreActivity(activity) | ||||||||||
| Get the Activity which generated the given entity. | synGetActivity(entity) / synGetActivity(entityId) | ||||||||||
| Set the Activity which generated the given entity | synSetActivity(entity)<-activity | ||||||||||
| Empty trash can | |||||||||||
| Restore from trash can | |||||||||||
| Run code, capturing output, code and provenance relationship. | synapseExecute(executable, args, resultParentId, codeParentId, resultEntityProperties = NULL, resultEntityName=NULL, replChar=".") | synapseExceute(executable, args, resultParentId, codeParentId, resultEntityProperties = None, resultEntityName=None, replChar=".") | |||||||||
| Create evaluation object | Evaluation(name, description, status) | Evaluation(name, description, status) | |||||||||
| Join evaluation | addParticipant(evaluation, principalId) | evaluation.addParticipant(principalId) | |||||||||
| Submit for evaluation | submit(evaluation, entity) | evaluation.submit(entity) | |||||||||
| 3 – Web API Level | |||||||||||
| Execute GET request | synRestGET(endpoint, uri) | ||||||||||
| Execute POST request | synRestPOST(endpoint, uri, body) | ||||||||||
| Execute PUT request | synRestPUT(endpoint, uri, body) | Execute DELETE request | synRestDELETE(endpoint, uri) | endpoint, uri, body) | |||||||
| Execute DELETE request | synRestDELETE(endpoint, uri) |
Endpoints
At the time of this writing, there are three endpoints for web service calls in our production system:
https://auth-prod.prod.sagebase.org/auth/v1
https://repo-prod.prod.sagebase.org/repo/v1
https://file-prod.prod.sagebase.org/file/v1
These are used to call the web APIs linked below.
Web APIs
The URIs, request bodies and request methods are defined by the Synapse Web APIs. The URIs omit the endpoints given above, e.g. to retrieve entity metadata the endpoint would be "https://repo-prod.prod.sagebase.org/repo/v1" while the URI might be "/entity/syn123456". The web APIs define request and response bodies in terms of JSON objects. In the analytic clients these are expressed as named lists or nested named list, e.g. in R the JSON object {"foo":"bar", "bas":"bah"} is passed in as list(foo="bar", bas="bah").
The Web APIs are defined here:
Common Configuration File
...