Current APIs

See Repository Service API for full examples of requests and responses. What follows are merely examples of the URL patterns for accessing the service using the HTTP methods GET to read an entity, POST to create an entity, PUT to update an entity, and DELETE to delete an entity.

Proposed APIs

Proposed API for EULAs

EULA = end user license agreement

Assumptions

EULA entity

A EULA is yet another entity (node) in the repository service and has the following additional fields:

{
  "name": "TCGA Redistribution Use Agreement",
  "agreement": "The recipient acknowledges that the data herein is provided by TCGA and not SageBionetworks and must abide by ..."
}

The entity kind is 'eula':

POST/GET/PUT/DELETE /repo/v1/eula/#

Dataset to EULA mapping

Datasets will have a new field called eulaId which may be null.

Agreements: User to EULA mapping

There will be a table to record when users agree to EULAs.
The structure of this table will be:

datasetId

datasetVersionId

eulaId

eulaVersionId

userId

agreementDate

Downloading Data

When a user tries to get a location for a dataset or layer:

Making an Agreement

Determining in advance whether a user needs to agree:

/repo/v1/query?query=select * from agreement where datasetId=='123' and eulaId='456' and userId='789'

Proposed API for Projects

This work is done.

Proposed API for Actions

Proposed API for Analyses

Proposed API for downloading datasets or layers

This is mostly done, except for enforcing authentication and authorization along with the eula.

Proposed API for Free Text Search

Proposed Annotation Type API

JSON Schema Resources

Positive Integer Annotation

POST /repo/v1/annotationtype
      {
         "name":"numberOfSamples",
         "displayName":"Number of Samples",
         "schema":{
            "description":"The number of samples in a dataset layer.",
            "type":"integer",
            "minimum":1
         }
      }

Enumerated Type Annotation

POST /repo/v1/annotationtype
      {
         "name":"status",
         "displayName":"Status",
         "schema":{
            "description":"The status of a dataset.",
            "type":"string",
            "enum":[
               "unknown",
               "pending",
               "curated",
               "QCed"
            ],
            "default":"unknown"
         }
      }

Very Long String Annotation

POST /repo/v1/annotationtype
      {
         "name":"curationNotes",
         "displayName":"Curation Notes",
         "schema":{
            "description":"The free text notes on curation that did not have a proper home in the ISA-Tab representation of the dataset metadata.",
            "type":"string",
            "maxLength":4096
         }
      }

Ontology Annotation

POST /repo/v1/annotationtype
      {
         "name":"tissueType",
         "displayName":"Tissue Type",
         "schema":{
            "description":"The type of tissue in a dataset layer.",
            "type":"string",
            "format":"TODO URL to the ontology we are using for this"
         }
      }

Array of Values Annotation

POST /repo/v1/annotationtype
      {
         "name":"tissueTypes",
         "displayName":"Tissue Types",
         "schema":{
            "description":"The types of tissue in a dataset.",
            "type":"array",
            "items":{
               "type":"string",
               "format":"TODO URL to the ontology we are using for this"
            }
         }
      }

Proposed API for Batch Requests

Ultimately we would like to support a full-on batch implementation similar to https://developers.facebook.com/docs/api/batch/ that would allow fully independent requests to be issued in batch

BATCH REQUEST

curl \
    –F 'access_token=…' \
    -F 'batch=[ \
          { "method": "POST", \
            "relative_url": "me/feed", \
            "body": "message=Test status update&link=http://developers.facebook.com/" \
          }, \
          { "method":"GET", \
            "relative_url":"me/feed?limit=1" \
          } \
        ]'\
    https://graph.facebook.com

BATCH RESPONSE

[
    { "code": 200,
      "headers": [
          { "name":"Content-Type", 
            "value":"text/javascript; charset=UTF-8"}
       ],
      "body":"{\"id\":\"…\"}"
    },
    { "code": 200,
      "headers": [
          { "name":"Content-Type", 
            "value":"text/javascript; charset=UTF-8"
          },
          { "name":"ETag", 
            "value": "…"
          }
      ],
      "body": "{\"data\": [{…}]}
    }
]

We have an immediate need for one particular API to support batch requests and in the interest of time could go with something more simple:

BATCH REQUEST

GET /repo/v1/entity/type?batch=123,456,789

BATCH RESPONSE

{
  "paging": {},
  "results": [
              {
               "id":"123",
               "name":"Example Dataset 1",
               "type":"/dataset"
              },
              {
               "id":"456",
               "name":"Example Dataset 2",
               "type":"/dataset"
              },
              {
               "id":"567",
               "name":"Example Dataset 3",
               "type":"/dataset"
              },
             ],
  "totalNumberOfResults": 3
}
And so on:
GET /entity/type?batch=123,456,789
GET /entity/annotations?batch=123,456,789
GET /entity/s3Token?batch=123,456,789
GET /entity/acl?batch=123,456,789
Each returning PaginatedResults<T> where T is what ever /entity/<the id>/<the suffix> would return.

Requirements and Design Goals

Strongly Recommended

Nice To Have

Options

Options Considered

Options Ruled Out Early

REST Details

REST is merely guidance on your API. Its not actually a protocol.

Good intro to REST presentation http://www.slideshare.net/guestb2ed5f/scalable-reliable-secure-rest

Spring MVC 3.0 added many more features to make REST-ful services easier to write.

Some REST-ful API Examples

Helpful Links to HTTP protocol Spring stuff:

Google Data Protocol Details

Google Data Protocol is a REST-ful protocol based upon ATOM and JSON used by many Google APIs

OData Data

OData is a REST-ful protocol based upon ATOM and JSON and backed by Microsoft.

More Details

APIKeys for Authentication and Authorization

(proposal from Bruce here)

HTTP Methods

Some browsers and/or firewalls do not support PUT or DELETE operations. Here are two commons work arounds: