HTTP API

From SynBioHubWiki
Jump to: navigation, search

SynBioHub exposes the following HTTP endpoints:

GET endpoint to count objects

GET <SynBioHub URL>/<ObjectType>/count

e.g. curl -X GET https://synbiohub.org/Collection/Count

Note that you can replace Collection with any object type, such as ComponentDefinition, SequenceAnnotation, etc.

POST endpoint to request to login

This POST request requires email/password and returns a user token needed for viewing private objects and submitting new objects.

POST http://synbiohub.org/login

Parameters:

  • email : the e-mail address of the user to login with
  • password : the password of the user

Returns a string token to be passed with any call to submit as the user parameter.

e.g. curl -X POST -H "Accept: text/plain" -d "email=<email>&password=<password>" https://synbiohub.org/login

GET endpoint that returns all Collections that are not members of any other Collection

GET <SynBioHub URL>/rootCollections

e.g. curl -X GET -H "Accept: text/plain" -H "X-authorization: <token>" https://synbiohub.org/rootCollections

Note that the X-authorization header is optional, but if provided, it will also return private root collections for the logged in user.

GET endpoint that returns all Collections that are members of the Collection specified by its URI

GET <URI>/subCollections

e.g. curl -X GET -H "Accept: text/plain" -H "X-authorization: <token>" https://synbiohub.org/public/igem/igem_collection/1/subCollections

Note that the X-authorization header is not needed for public collections, but it is required for private collections.

GET endpoint that returns SBOL for the object with the specified URI

GET <URI>/sbol

e.g. curl -X GET -H "Accept: text/plain" -H "X-authorization: <token>" https://synbiohub.org/public/igem/BBa_F2620/1/sbol

Note that the X-authorization header is not needed for public objects, but it is required for private objects.

GET endpoint that returns source for an attachment with the specified URI

GET <URI>/download

e.g. curl -X GET -H "Accept: text/plain" -H "X-authorization: <token>" https://synbiohub.org/public/test/attachment_00009TGVMsfEoCdMeRzHrU/1/download -O --compressed

Note that the X-authorization header is not needed for public attachments, but it is required for private attachments.

POST endpoint that attaches a file to a specified URI

POST <URI>/attach

e.g. curl -X POST -H "Accept: text/plain" -H "X-authorization: <token>" -F 'file=@<filename>' https://synbiohub.org/user/MyUserName/test/test_collection/1/attach

GET endpoint to perform a search and return metadata

GET <SynBioHub URL>/search/<key>=<value>&...&<search string>/?offset=#&limit=#

e.g. curl -X GET -H "Accept: text/plain" -H "X-authorization: <token>" 'https://synbiohub.org/search/objectType%3DComponentDefinition%26role%3D%3Chttp%3A%2F%2Fidentifiers.org%2Fso%2FSO%3A0000316%3E%26GFP/?offset=0&limit=50'

Note that the X-authorization header is optional, but if provided, the search will also return private objects for the logged in user.

Before URL encoding, the URL is composed of a series of search criteria of the form:

key=value&

The key/value pair can be one of the following:

  • objectType=value : The type of object to search for (e.g. objectType=ComponentDefinition&)
  • sbolTag=value : A tag in the SBOL namespace to search for (e.g. role=<http://identifiers.org/so/SO:0000316>&)
  • collection=value : Matches objects that are members of the specified collection (e.g., collection=<http://synbiohub.org/public/igem/igem_collection>&)
  • dcterms:tag=value A tag in the dcterms namespace to search for (e.g. dcterms:title='pLac'&) - note this requires an exact match
  • namespace/tag=value A full namespace with tag separated by appropriate delimiter (e.g. <http://sbols.org/v2#role>=<http://identifiers.org/so/SO:0000316>&)

After the key/value pairs, an optional search string can be provided that will be used to search for partial matches in the displayId, name, or description fields.

Finally, the URL can end with an offest and limit parameter.

This endpoint returns JSON metadata of the form

[
    {
        "uri":"http://synbiohub.org/public/igem/BBa_K1404008/1",
        "name":"BBa_K1404008",
        "description":"p70-CsgA-His*2, double His-tagged curli generator",
        "displayId":"BBa_K1404008",
        "version":"1"
    },

    ...
]

GET endpoint to perform a search and return count of search results

GET <SynBioHub URL>/searchCount/<key>=<value>&...&<search string>/?offset=#&limit=#

e.g. curl -X GET -H "Accept: text/plain" -H "X-authorization: <token>" 'https://synbiohub.org/searchCount/objectType%3DComponentDefinition%26role%3D%3Chttp%3A%2F%2Fidentifiers.org%2Fso%2FSO%3A0000316%3E%26GFP'

Returns the number of items matching the search result.

Note that the X-authorization header is optional, but if provided, the search count will also include private objects for the logged in user.

POST endpoint to create a new collection

POST <SynBioHub URL>/submit

e.g. curl -X POST -H "Accept: text/plain" -H "X-authorization: <token>" -F id=<id> -F version=<version> -F name=<name> -F description=<description> -F citations=<citations> -F overwrite_merge=<overwrite_merge> -F file=@<filename> https://synbiohub.org/submit

Parameters:

  • id : a user-defined string identifier for the submission; alphanumeric and underscores only, e.g. BBa_R0010
  • version : the version string to associate with the submission, e.g. 1
  • name : the dcterms name string to assign to the submission
  • description : the dcterms description string to assign to the submission
  • citations : a list of comma separated pubmed IDs of citations to store with the submission
  • overwrite_merge : '0' prevent if submission exists, '1' overwrite if submission exists
  • file : contents of an SBOL2, SBOL1, GenBank, FASTA, ZIP, or COMBINE Archive file

POST endpoint to add to an existing collection

POST <SynBioHub URL>/submit

e.g. curl -X POST -H "Accept: text/plain" -H "X-authorization: <token>" -F rootCollections=<URI> -F overwrite_merge=<overwrite_merge> -F file=@<filename> https://synbiohub.org/submit

Parameters:

  • rootCollections : URI of the private root collection to add content to
  • overwrite_merge : '2' prevent if submission exists, '3' overwrite if submission exists
  • file : contents of an SBOL2, SBOL1, GenBank, FASTA, ZIP, or COMBINE Archive file




Newcastle-university.png Icos.png University-utah.png   AntarcticDesign.png