Skip to content

Instantly share code, notes, and snippets.

@will-moore

will-moore/webgateway_json_api.md

Last active April 7, 2016 12:52
Show Gist options
  • Star 2 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save will-moore/2aa7d5eef6481dd3c777 to your computer and use it in GitHub Desktop.
Save will-moore/2aa7d5eef6481dd3c777 to your computer and use it in GitHub Desktop.
Download ZIP
Raw
webgateway_json_api.md

API Overview

The OMERO json API described here is available from OMERO 5.3.0 release at the location

<server>/api/

Pagination

Requests that return a number of items will be paginated by default.

Parameters

Name        Type        Description
------------------------------------------------------------------
page        Number      Page number, starting at page=1 (default)
                        Can use page=0 to disable pagination return all results
limit       Number      The size of each page. The default can be set in
                        $ bin/omero config set omero.web.page_size 100

Error handling

Invalid parameters or invalid JSON will result in a 400 Bad Request:

{"message": "Invalid parameter value"}

Unhandled exceptions are handled with a 500 error response that will include the error

Groups and Experimenters

List groups

You can list all the groups on the OMERO server

GET     /groups/

Parameters

Name        Type        Description
------------------------------------------------------------------
member      Number      Only return Groups that the experimenter is a member of
owner       Number      Only return Groups that the experimenter is an owner of

Response

{
  data: [
    {
      id: 6732,
      perm: "rwr---",
      name: "Lab Group"
    }
  ]
}

List experimenters

You can list all the experimenters on the OMERO server

GET     /experimenters/

Parameters

Name        Type        Description
------------------------------------------------------------------
group       Number      Only return experimenters that belong to this group
admin       Boolean     If true, only return Admin experimenters
active      Booleean    If true, only return active experimenters

Response

{
  data: [
    {
      id: 3829,
      omeName: "will",
      firstName: "William",
      lastName: "Moore",
      email: "will@dundee.uk"
    }
  ]
}

Get a single experimenter

GET     /experimenters/:id

Response

{
  data: {
    id: 3829,
    omeName: "will",
    firstName: "William",
    lastName: "Moore",
    email: "will@dundee.uk"
  }
}

image containers

OMERO organises images in 2 types of many-to-many hierarcies: screen/plate/[Run]/Well/image for HCS data and projects/datasets/images for other data. images can also be Orphaned if not contained within a Well or dataset. OMERO also supports Shares, which provide more permissive access to the list of images linked to a Share.

List all top-level containers

List containers that are not children of other containers. This includes a virtual Orphaned images container that gives the number of orphaned images. This is equivalent to the initial display of data in the clients.

GET    /containers/

Parameters

Name        Type        Description
------------------------------------------------------------------
group       Number      Only return containers from this group
owner       Number      Only return containers owned by this user

Response

{
  data: {
    projects: [],
    datasets: [],
    screens: [],
    plates: [],
    orphaned: {
      id: -1,     # currently this is the experimenter_id
      name: "Orphaned images",
      childCount: 56
    }
  }
}

List projects

GET     /projects/

Parameters

Name        Type        Description
------------------------------------------------------------------
group       Number      Only return projects from this group
owner       Number      Only return projects owned by this user

Response

{
  data: [
    {
      id: 1101,
      owner: {
        id: 4
      },
      group: {
        id: 3
      }
      childCount: 4,
      permissions: {canEdit: true, canAnnotate: true, canLink: true, canDelete: false}
      name: "Ben's project"
    }
]}

Create a project

POST    /projects/

Parameters

Name        Type        Description
------------------------------------------------------------------
group       Number      The group to which the project is assigned
name        String      Required. The name of the project
description String      The description of the project

Response

201 Created
{
  data: {
    id: 8247,
    name: "My new project",
    description: "Testing this",
    owner, {
      id: 4
    },
    group, {
      id: 3
    }
  }
}

Get a single project

GET   /projects/:projectId

Response

{
  data: {
    "id": 668,
    "name": "Yeast Mitosis",
    "description": ""
  }
}

Delete a project

POST  /projects/:projectId

Response

204   No Content

List datasets

GET     /datasets/

Parameters

Name        Type        Description
------------------------------------------------------------------
group       Number      Only return datasets from this group
owner       Number      Only return datasets owned by this user
project     Number      List datasets that are children of this project
orphaned    Boolean     If true, only return datasets not contained
                        within a project. Default False

Response

{
  data: [
    {
      id: 5001,
      owner: {
        id: 3
      },
      childCount: 3,
      permissions: {canEdit: true, canAnnotate: true, canLink: true, canDelete: false}
      name: "My dataset"
    }
  ]
}

Create a dataset

POST    /datasets/

Parameters

Name        Type        Description
------------------------------------------------------------------
group       Number      The group to which the dataset is assigned
name        String      Required. The name of the dataset
description String      The description of the dataset

Response

201 Created
{
  data: {
    id: 8377,
    name: "New dataset Name",
    description: "Description text",
    owner, {
      id: 4
    },
    group, {
      id: 3
    }
  }
}

Get a single dataset

GET   /datasets/:datasetId

Response

{
  data: {
    "id": 879,
    "name": "Big dataset",
    "description": "Lots of images here"
  }
}

Delete a dataset

POST  /datasets/:datasetId

Response

204   No Content

List datasets in a project

This is the equivalent of /datasets/?project=:projectId

GET     /project/:projectId/datasets/

Parameters

Name        Type        Description
------------------------------------------------------------------
owner       Number      Only return datasets owned by this user

Response

# As for List datasets above

Create a dataset in a project

POST    /projects/:projectId/datasets/

Parameters

# As for Create dataset above

Response

# As for Create dataset above

List screens

GET     /screens/

Parameters

Name        Type        Description
------------------------------------------------------------------
group       Number      Only return screens from this group
owner       Number      Only return screens owned by this user

Response

{
  data: [
    {
      id: 3141,
      owner: {
        id: 4
      },
      childCount: 31,
      permissions: {canEdit: true, canAnnotate: true, canLink: true, canDelete: false}
      name: "siRNAi screen 1"
    }
]}

Create a screen

POST    /screens/

Parameters

Name        Type        Description
------------------------------------------------------------------
group       Number      The group to which the screen is assigned
name        String      Required. The name of the screen
description String      The description of the screen

Response

201 Created
{
  data:
    id: 8247,
    name: "My new screen",
    description: "Testing this",
    owner, {
      id: 4
    },
    group, {
      id: 3
    }
  }
}

List plates

GET     /plates/

Parameters

Name        Type        Description
------------------------------------------------------------------
group       Number      Only return plates from this group
owner       Number      Only return plates owned by this user
screen      Number      List plates that are children of this screen
orphaned    Boolean     If true, only return plates not contained
                        within a screen. Default False

Response

{
  data: [
    {
      id: 5721,
      owner: {
        id: 4
      },
      childCount: 25,
      permissions: {canEdit: true, canAnnotate: true, canLink: true, canDelete: false}
      name: "Treatment plate"
    }
]}

List plates in a screen

This is the equivalent of /plates/?screen=:screenId

GET     /screens/:screenId/plates/

Parameters

Name        Type        Description
------------------------------------------------------------------
owner       Number      Only return plates owned by this user

Response

# As for List plates above

List plate Runs

GET   /runs/

Parameters

Name        Type        Description
------------------------------------------------------------------
group       Number      Only return plates from this group
owner       Number      Only return plates owned by this user
plate       Number      List Runs that are children of this plate

Response

{
  data: [
    {
      id: 52,
      owner: {
        id: 3
      },
      permissions: {canEdit: true, canAnnotate: true, canLink: true, canDelete: false}
      name: "Run Name 3"
    }
  ]
}

List Runs in a plate

This is the equivalent of /runs/?plate=:plateId

GET     /plates/:plateId/runs/

Parameters

Name        Type        Description
------------------------------------------------------------------
owner       Number      Only return Runs owned by this user

Response

# As for List Runs above

List Paths to an Object

In order to reveal a specified object in the above hierarchies, it is useful to know the path(s) from parent top-level objects. Object types supported are project, dataset, image, screen, plate, run, well. If type is image and the image is in a dataset, then we do not also check if the image is in a plate and Well.

GET   /paths/:objectType/:objectId/

Parameters

TODO: do we need these parameters??

Name        Type        Description
------------------------------------------------------------------
owner       Number      Only return paths that include this experimenter
                        (where they own the top level object)
project     Number      Only return paths that include this project
dataset     Number      Only return paths that include this dataset
screen      Number      Only return paths that include this screen
plate       Number      Only return paths that include this plate

Response

TODO: should include "well" and "image" in path (not needed in jsTree but API should provide them)

Image in a dataset(s):

{
  data: [
    [
      {
        type: "experimenter",
        id: 3
      },
      {
        type: "project",
        id: 7301
      },
      {
        type: "dataset",
        id: 9701
      },
      {
        type: "image",
        id: 6901
      }
    ],
    [
      {
        type: "experimenter",
        id: 3
      },
      {
        type: "dataset",
        id: 10851
      },
      {
        type: "image",
        id: 6901
      }
    ]
  ]
}

Image in a plate and Well:

{
  data: [
    [
      {
        type: "experimenter",
        id: 3
      },
      {
        type: "screen",
        id: 701
      },
      {
        type: "plate",
        id: 752
      },
      {
        type: "run",
        id: 402
      }
    ]
  ]
}

Shares and Discussions

Shares are virtual containers that allow users to view a collection of images that are not accessible to them under the regular OMERO permissions, and to add Comments. Discussions simply allow a series of Comments without including images.

List Shares

GET   /shares/

Parameters

Name        Type        Description
------------------------------------------------------------------
owner       Number      Only return shares owned by this user
member      Number      Return shares where this user is a member

Response

{
  data: [
    {
        id: 4602,
        owner: {
          id: 3
        },
        active: false,
        expired: false,
        childCount: 3,
    }
  ]
}

List Discussions

GET   /discussions/

Parameters

# As for List Shares above

Response

{
  data: [
    {
        id: 25775,
        owner: {
          id: 3
        },
        active: true,
        expired: false
    }
  ]
}

List Shares and Discussions

GET   /publicContainers/

Parameters

# As for List Shares above

Response

{
  data: {
    discussions: [
      {
          id: 25775,
          owner: {
            id: 3
          },
          active: true,
          expired: false
      }
    ],
    shares: [
      {
          id: 4602,
          owner: {
            id: 3
          },
          active: false,
          expired: false,
          childCount: 3,
      }
    ]
  }
}

List images In Share

GET   /shares/:share_id/images/

Response

{
  data: [
    {
      id: 4718,
      name: "GFP-INCENP01.tif",
      fileset: {
        id: 3666
      },
      pixels: {
        sizeX: 1344,
        sizeY: 1040,
        sizeZ: 1
      }
      creationDate: "2014-09-10T16:36:29Z",
      owner: {
        id: 4
      },
      share: {
        id: 134198
      }
    }
  ]
}

Images

List images

GET   /images/

Parameters

Name        Type        Description
------------------------------------------------------------------
group       Number      Only return images from this group
owner       Number      Only return images owned by this user
dataset     Number      List images that are children of this dataset
orphaned    Boolean     If true, only return images not contained
                        within a dataset or Well. Default False
embed       String      List of objects to include.
                        E.g. ?embed=thumbnail,pixels.sizeX,pixels.sizeY

Response

{
  data: [
    {
      id: 16783,
      owner: {
        id: 3
      },
      name: "test.dv",
      permissions: {canEdit: true, canAnnotate: true, canLink: true, canDelete: false}
      fileset: {
        id: 9751
      },
      acquisitionDate: "2009-02-27T10:25:32Z",
      creationDate: "2015-10-22T11:57:06Z",
      pixels: {
        sizeX: 512,
        sizeY: 512,
        sizeZ: 29
      },
      thumbnail: {
        version: 0
      },
    }
  ]}

Tags

Tags can be organised into Tag sets which are simply Tags with a defined namespace. Listing Tags will give a collection that may include Tags and Tag sets. Tag sets will have tagset: true attribute.

List Tags

GET   /tags/

Parameters

Name        Type        Description
------------------------------------------------------------------
group       Number      Only return Tags from this group
owner       Number      Only return Tags owned by this user
tagset      Number      List Tags that are children of this Tag set
orphaned    Boolean     If true, only return Tags not contained
                        within a Tag set. Default False

Response

{
  data: [
    {
      id: 655,
      owner: {
        id: 3
      },
      tagset: false,
      permissions: {canEdit: true, canAnnotate: true, canLink: true, canDelete: false}
      value: "Control",
      childCount: 5
    }
  ]
}

List Tagged Objects

GET   /tagged/:tagId/

Parameters

Name        Type        Description
------------------------------------------------------------------
owner       Number      Only return objects owned by this user

Response

{
  data: {
    projects: [],
    datasets:[],
    images: [],
    screens: [],
    plates: [],
    runs: [],
    tags: []
  }
}

Linking and Unlinking Objects

Links between the following objects can be created or deleted:

  • project and dataset
  • dataset and image
  • screen and plate
  • Tag / Tag set and Tag
  • Tag and:
    • project
    • dataset
    • image
    • screen
    • plate

Create Links

POST  /links/

Input

You need to provide a list of link objects to create.

Name        Type        Description
------------------------------------------------------------------
parentType  String      One of project, dataset, screen, tag, tagset
parentId    Number      Id of the parent object
childType   String      One of dataset, image, plate, tag
childId     Number      Id of the child object

Example

{
  links: [
    {
      "parentType": "project",
      "parentId": 10,
      "childType": "dataset",
      "childId": 5
    },
    {
      "parentType": "tagset",
      "parentId": 42,
      "childType": "tag",
      "childId": 49
    }
  ]
}

Response

{
  data: [
    {
      "id": 879,
      "parentType": "project",
      "parentId": 10,
      "childType": "dataset",
      "childId": 5
    },
    {
      "id": 668,
      "parentType": "tagset",
      "parentId": 42,
      "childType": "tag",
      "childId": 49
    }
  ]
}

Delete Links

Links between objects can be deleted in the same way as created. In this case, we return a list of any links that remain on the child objects so that we can tell if they have become Orphaned.

DELETE  /links/

Input

# Links defined as above for Create Links

Response

{
  data: [
    {
      "id": 879,
      "parentType": "project",
      "parentId": 10,
      "childType": "dataset",
      "childId": 5
    }
  ]
}

Urls for listing objects: matrix of query paramters

                page    limit   owner   group   member    orphaned  project dataset screen  plate   tag     tagset
groups          x       x                       x
experimenters   x       x               x  
containers      x       x       x       x                                                           
projects        x       x       x       x                                                           
datasets        x       x       x       x                 x         x                              
images          x       x       x       x                 x                 x
screens         x       x       x       x 
plates          x       x       x       x                 x                         x      
runs            x       x       x       x                                                   x       
tagged          x       x       x                                                                   R
tags            x       x       x       x                 x                                                 x  
shares          x       x       x               x

All parameters are optional except 'R' (required)

  • page: Page index for pagination

  • limit: number of objects per page

  • owner: filter objects by owner

  • group: filter objects or experimenters by their group

  • member: filter groups or shares that user belongs to

  • orphaned: only return objects that have no parent container

  • images and tagged urls: boolean parameters for getting extra info for images

    • sizeXYZ: get image sizeX, sizeY & sizeZ
    • date: get image import 'date' and acquisition date acqDate
    • thumbVersion (not for tagged): get current thumbnail version

Other urls

links           json: {"dataset":{"10":{"image":[1,2,3]}}}
api_tags_and_tagged_list_DELETE  ids
paths_to_object  experimenter, project, dataset, image, screen, plate, run/acquisition, well, group
@will-moore
Copy link
Author

Update shares to use parameters member and owner instead of member_id and owner_id
Change experimenter_id to owner for tagged_tags and images

@will-moore
Copy link
Author

Update containers to use owner instead of id to specify owner.

@will-moore
Copy link
Author

Split tags_and_tagged into 2 urls: tags and tagged.
Where tagged returns ALL tagged objects: P/D/I/S/P and Tags
and tags lists tags, similar to projects etc.

@will-moore
Copy link
Author

Add orphaned parameter to datasets and plates urls.

@will-moore
Copy link
Author

Rename views methods to match their url "name" (remove _list from each). E.g. api_datasets.

@will-moore
Copy link
Author

Added projects url

@will-moore
Copy link
Author

Add owner parameter to datasets, plates and projects urls.

@will-moore
Copy link
Author

Added individual project, dataset etc query params instead of ambiguous id parameter.

@will-moore
Copy link
Author

Renamed plate_acquisitions to runs and added params: page, limit, owner, group, plate

@will-moore
Copy link
Author

Added screens url

@will-moore
Copy link
Author

Started a section on Error Handling.

@will-moore
Copy link
Author

Use permissions instead of permsCss for returned object permissions. This was previously used for css but not now.

@will-moore
Copy link
Author

Tag has tagset boolean attribute.

@will-moore
Copy link
Author

Removed isOwned from returned shares and discussions

@sbesson
Copy link

sbesson commented Mar 22, 2016

typo: pubicContainers should be renamed as publicContainers (I hope)

@sbesson
Copy link

sbesson commented Mar 22, 2016

tagged owner: is this meant to be Only return Objects owned by this user ?

@will-moore
Copy link
Author

Thanks @sbesson - fixed both those.

@atarkowska
Copy link

Is lack of envelope on returning single object https://gist.github.com/will-moore/2aa7d5eef6481dd3c777#get-a-single-experimenter intentional ? If we use envelope it should be consistent everywhere, no?

@knabar
Copy link

knabar commented Mar 31, 2016

Regarding pagination, I find it more intuitive to have limit=0 return all results and start paging at page zero instead of 1, or alternatively use a start argument that allows arbitrary start offsets independent of page size, also starting at zero.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment