Web Service API

The Apollo Web Service API is a JSON-based REST API to interact with the annotations and other services of Apollo. Both the request and response JSON objects can contain feature information that are based on the Chado schema. We use the web services API scripting examples and we also use them in the Apollo JBrowse plugin.

The most up to date Web Service API documentation is deployed from the source code rest-api-doc annotations.

See http://icebox.lbl.gov/Apollo2/jbrowse/web_services/api for details

What is the Web Service API?

For a given Apollo server url (e.g., https://localhost:8080/apollo or any other Apollo site on the web), the Web Service API allows us to make requests to the various “controllers” of the application and perform operations.

The controllers that are available for Apollo include the AnnotationEditorController, the OrganismController, the IOServiceController for downloads of data, and the UserController for user management.

Most API requests will take:

  • The proper url (e.g., to get features from the AnnotationEditorController, we can send requests to (e.g http://localhost/apollo/annotationEditor/getFeatures)
  • username - an authorized user (also uses session if none specified)
  • password - password (also uses session if none specified)
  • organism - (if applicable) the “common name” of the organism for the operation – will also pull from the “user preferences” if none is specified.
  • track/sequence - (if applicable) reference sequence name (shown in sequence panel / genomic browse)
  • uniquename - (if applicable) the uniquename is a UUID used to guarantee a unique ID

Errors If an error has occurred, a proper HTTP error code (most likely 400 or 500) and an error message. is

returned, in JSON format:

{ "error": "error message" }

Additional Notes

If you are sending password you care about over the wire (even if not using web services) it is highly recommended that you use https (which adds encryption ssl) instead of http.

Examples are provided in the docs/web_services/examples/groovy/ directory for using SSL and optionally ignoring certificates.


curl -b cookies.txt -c cookies.txt -e "http://localhost:8080" \
    -H "Content-Type:application/json" \
    -d "{'username': 'demo', 'password': 'demo'}" \

Login expects two parameters: username and password, and optionally rememberMe for a persistent cookie.

A successful login returns a empty JSON object


The Apollo Login creates a JSESSIONID cookie and rememberMe cookie (if applicable) and these can be used in downstream API requests (for example, by setting -b cookies.txt in curl will preserve the cookie in the request).

You can also pass username/password to individual API requests and these will authenticate each individual request.

Representing features in JSON

Most requests and responses will contain an array of feature JSON objects named features. The feature object is based on the Chado feature, featureloc, cv, and cvterm tables.

    "residues": "$residues",
    "type": {
        "cv": {
            "name": "$cv_name"
        "name": "$cv_term"
    "location": {
        "fmax": $rightmost_intrabase_coordinate_of_feature,
        "fmin": $leftmost_intrabase_coordinate_of_feature,
        "strand": $strand
    "uniquename": "$feature_unique_name"
    "children": [$array_of_child_features]
    "properties": [$array_of_properties]


  • residues - A sequence of alphabetic characters representing biological residues (nucleic acids, amino acids) [string]
  • type.cv.name - The name of the ontology [string] type.name - The name for the cvterm [string]
  • location.fmax - The rightmost/maximal intrabase boundary in the linear range [integer]
  • location.fmin - The leftmost/minimal intrabase boundary in the linear range [integer]
  • strand - The orientation/directionality of the location. Should be 0, -1 or +1 [integer]
  • uniquename - The unique name for a feature [string]
  • children - Array of child feature objects [array]
  • properties - Array of properties (including frameshifts for transcripts) [array]

Note that different operations will require different fields to be set (which will be elaborated upon in each operation section).

Web Services API

The most up to date Web Service API documentation is deployed from the source code rest-api-doc annotations

See http://icebox.lbl.gov/Apollo2/jbrowse/web_services/api for details