Propsal for Layers and Locations

History

Currently, Layers are implemented as first class entities recognized by Synapse. A Layer can be composed of one or more child Locations. These child Locations are also first class entities recognized by Synapse. Since a Location is first class Entity, access to the Location can be micro-managed by overriding an ACL. Locations are currently the only "Versionable" Synapse Entity.

While there are some advantages to Locations being first class entities, for the most part this just causes confusion for our API users. In fact, our client developers have gone to great lengths to hide the true relationship between Layers and their Locations from end-users. Our end-users do not see locations as first class objects, but rather as data of a Layer.

So why are Locations a separate first class entity rather than simply data of a Layer? The answer is, there currently is a limit to the types of data that can stored in any Synapse Entity. Currently, we can only support Entities that have primitive data, and lists (or arrays) of primitives data. We cannot support an Entity that uses object composition. To correctly support location data in layer we would need some type of object composition.

Proposal

New Layer Object

We are proposing that we add support for object composition in entities. This would allow us to represent locations as data of a first class Layer entity.

Figure 1.

In figure 1, the Layer is an entity that implements Versionable and has a List of Locations which are simple POJOs and not entities. This implies that all location C.R.U.D. operations will be done via the Layer API. All location API calls will be removed.

Example Layer JSON

{
  "etag": "0",
  "id": "17338",
  "md5sum": "b513a23fc54b7b0d65312e1a900af5a6",
  "name": "Best Layer Ever!",
  "parentId": "17337",
  "uri": "/repo/v1/layer/17338",
  "versionComment": null,
  "versionLabel": "0.0.0",
  "versionNumber": 1,
  "versionUrl": "/repo/v1/layer/17338/version/1",
  "versions": "/repo/v1/layer/17338/version"
  "locations": [
    {
      "type": "awss3",
      "path": "https://s3.amazonaws.com/stagingdata.sagebase.org/17338/0.0.0/mskcc_prostate_cancer.phenotype.zip?Expires=1317918889&AWSAccessKeyId=AKIAJQBSYCAUPIYF5WTA&Signature=2vTczuWgJ88Z0tiau1%2BPse4L2NA%3D",
      "contentType": "XML",
    },
    {
      "type": "local",
      "path": "c:/myDocuments/mskcc_prostate_cancer.phenotype.zip",
      "contentType": "JSON",
    }
}

Location Permission

For now, we are proposing "hard-coding" that a user must belong to the AUTHENTICATED_USERS group to see location data of a layer. This means if a user is not authenticated (anonymous) and allowed to READ a Layer, then they will get a receive a Layer object with the location data stripped out.

If we find we need true more fine-grained control over Layer location access then we can add a new Permission called DOWNLOAD, that will control the visibility of location data.