Genes Phenotypes Help, News, Blog

Impress API Documentation

General

  • All url paths should be prefixed with /impress, e.g. http://api.mousephenotype.org/impress/pipeline/list
  • All requests are GET requests unless otherwise stated.
  • The change log is linked from the Phenodcc Homepage, alongside changelogs for all our other web services.

Glossary

  • Spine – The core, denormalised part of the schema, starting with the Pipeline and ending with the options & increments. For example:Pipelines consist of Schedules which contain Procedures containing Parameters which contain Options & Increments

Spine

General

/:type/:id

The most low-level getter for objects in the interface. Returns a single instance of the identified object

  • :type An object type from: increment, ontologygroup, ontologyterm, option, parameter, parammpterm, pipeline, paramontologyoption, procedure, schedule, sop, unit, parametergroup
  • :id The identifier for the object (NOT KEY) – the unique id for the object to return.

/:type/multiple (POST)

This is a way of batching requests to the above call. Provide the type in the URL, and a list of IDs in JSON format – e.g. [ 3, 32, 66 ] in the body of the call. Note – ensure that the content type of the request is also set to application/json.

Pipelines

/pipeline/bykey/:key

WSDL equivalent – PipelineClient

Get the pipeline specified by the given key

  • :key – The pipeline key to get

Data returned is a JSON representation of that instance of the pipeline.

/pipeline/list

Legacy – see /pipeline/list/:lod below – equivalent to /pipeline/list/names

/pipeline/list/:lod

WSDL equivalent – PipelineKeysClient

Get the pipelines in IMPReSS

  • :lod The level of detail to return – can be one of the following
    • full – returns the entire pipeline objects
    • names – returns just the pipeline names
    • keys – returns just the pipeline keys

Data is returned as a map with the pipeline ID as the key.

Schedules

/schedule/belongingtopipeline/:lod/:pipelineID

Gets the schedules beloinging to the provided pipeline

  • :lod The level of detail to return – can be one of the following
    • full – returns the entire schedule objects
    • summary – return just the schedule Ids and time Labels
  • :id The pipeline identifier – this can be either the pipeline key, or the pipeline unique ID number.

Procedures

/procedure/belongingtopipeline/:lod/:id

WSDL equivalent – ProcedureKeysClient

Gets the procedures belonging to the provided pipeline

  • :lod The level of detail to return – can be one of the following
    • full – returns the entire procedure objects
    • names – returns just the procedure names (Note: this used to be summary)
    • keys – returns just the procedure keys
  • :id The pipeline identifier – this can be either the pipeline key, or the pipeline unique ID number.

/procedure/belongingtoschedule/:id

Gets the procedures belonging to the provided schedule

  • :id The id of the schedule

Data is returned as a map with the procedure ID as the key.

/procedure/bykey/:key

Gets all instances of the procedure with the given key

  • :key – The key of the procedure

/procedure/bykey/:key/:pipekey

WSDL equivalent – ProcedureClient

Gets the procedure with the given key in the specified pipeline

  • :key – The key of the procedure
  • :pipekey – The key of the pipeline

Data returned is a JSON representation of that instance of the procedure.

/procedure/bylevel/:level

Retrieves all instances of procedures which have the provided level.

  • :level – The level to retrieve procedures for. Can be experiment, housing or line

/procedure/byname/:name

Retrieves all instances of procedures which have the provided name. (Be wary of URL-encoding)

  • :name – The name of the procedure to retrieve details for

/procedure/listnames

Convenience method – lists all unique procedure names

/procedure/getotherversions/:id

Returns a JSON object consisting of all the procedures in a pipeline, broken down by the schedule ID, procedure name, and procedure versions (earliest to latest)

  • :id – The id of the pipeline you want to find the procedures for.

Parameter

Note that at this point in the spine, due to the denormalisation, it no longer makes sense for this call to just accept a procedure key as a parameter.

This is because there could be multiple instances of the procedure key, due to the denormalisation, so the user needs to clarify which instance they are requesting.

This should be done by obtaining the procedure ID and using that in these subsequent calls. The preferred way of doing this is to make use of the /procedure/belongingtopipeline/:lod/:id call documented above, providing keys as the level of detail and the pipeline key as the id. The resulting JSON contains key-value pairs consisting of the unique procedure instance ID, and the corresponding procedure key. This can be stored in memory locally to provide a lookup to obtain the IDs for the following calls.

/parameter/byname/:name

Retrieves all instances of parameters which have the provided name. (Be wary of URL-encoding)

  • :name – The name of the parameters to retrieve details for

/parameter/belongingtoprocedure/:lod/:id

WSDL equivalent – ParametersClient

Gets the parameters belonging to the provided procedure instance

  • :lod The level of detail to return – can be one of the following
    • full – returns the entire parameter objects
    • names – returns just the parameter names (Note: this used to be summary)
    • keys – returns just the parameter keys
  • :id The procedure identifier – see notes under “Parameter” heading for how this should be obtained.

Data is returned as a map with the parameter ID as the key.

parameter/listnames

Convenience method – lists all unique parameter names

parameter/relatedtopipeline/:id

Returns all parameters that exist in the provided pipeline, grouped by procedure id.

  • :id The pipeline id.

Options

Calls to this level of the spine cannot be performed solely with a parameter key, due to the denormalisation. Before using these calls, obtain the id for the parameter instance you’re working with by using one of the parameter calls above.

option/belongingtoparameter/:lod/:id

WSDL equivalent – ParameterOptionsClient

Gets the option records belonging to the provided parameter instance

  • :lod The level of detail to return – can be one of the following
    • full – returns the entire option objects
    • names – returns just the option names (Note: this used to be summary)
  • :id The parameter identifier – see notes under “Option” heading for how this should be obtained.

option/relatedtoprocedure/:id

Returns a object containing the id of each parameter within the procedure along with an array of the options contained in those parameters

  • :id – The id of the procedure you wish to get the options for.

/option/listnames

Convenience method – lists all unique option names

Increments

Calls to this level of the spine cannot be performed solely with a parameter key, due to the denormalisation. Before using these calls, obtain the id for the parameter instance you’re working with by using one of the parameter calls above.

/increment/belongingtoparameter/:lod/:id

WSDL equivalent – ParameterIncrementsClient

Gets the increment records belonging to the provided parameter instance

  • :lod The level of detail to return – can be one of the following
    • full – returns the entire increment objects
    • names – returns just the increment names (Note: this used to be summary)
  • :id The parameter identifier – see notes under “Option” heading for how this should be obtained.

increment/relatedtoprocedure/:id

Returns a object containing the id of each parameter within the procedure along with an array of the increments contained in those parameters

  • :id – The id of the procedure you wish to get the increments for.

Ontology and MP Terms

Ontology Groups

/ontologygroup/list

Convenience method – Lists the names of the ontology groups on the system.

/ontologygroup/byname/:name

Works the same as /ontologygroup/:id, but allows the user to provide the name (Be wary of URL-encoding)

  • :name – The name of the ontologygroup to retrieve details for.

Ontology Options

/ontologyoption/optionsingroup/:id

Takes an ontology Group ID and returns details of all the ontology options within that group.

  • :id – The id of the ontologygroup to retrieve options for.

Ontology Terms

/ontologyterm/index

Convenience method – Provides an key-value index of ontology terms and ontology names.

/ontologyterm/belongingtoparameter/:parameterID

Produces a list of the ontology terms that are used with the provided procedure (that is, the MP* terms)

  • :parameterID – the ID of the parameter to retrieve results for.

/ontologyterm/byterm/:term

Works the same as /ontologyterm/:id, but allows the user to provide the ontologyterm in format MP:0000000

  • :term – The ontology term to retrieve details for.

/ontologyterm/linksbelongingtoparameter/:parameterID

Produces a list of the terms linked to the given parameter, such as INCREASED/DECREASED/ABNORMAL etc.

  • :parameterID – the ID of the parameter to retrieve results for.

/ontologyterm/list

Convenience method – Lists the ontology terms on the system.

/ontologyterm/termtree/:term

Returns part of the DAG where the provided ontology term is referenced

  • :term – The ontology term to retrieve details for.

Other

Units

/unit/list

Returns a list of the units in use on the system.

Appendix

‘Data Wrapper’

Previously some items were wrapped in JSON like so

 {data : content}

This has now been phased out of standard usage, however if you have a legacy system that depends on this format, you can append the following to the querystring of the API URLs to add the wrapper back in

usewrapper=true

Alternative Pipeline

Alternative pipeline contains the same procedures as the corresponding standard pipeline without the constraint on when the procedure should be performed. It is intended for capturing data on animals that cannot continue on the standard pipeline due to welfare issues.

These alternative versions of pipelines and procedures can be accessed by adding 1000000 to the pipeline ID for endpoints that accept IDs, and by prepending “ALT” to pipeline and procedure keys on endpoints that accept those. This will also show the necessary pipeline and procedure keys to be recorded in the XML for submission to the DCC. For example, the alternative IMPC pipeline is available at https://api.mousephenotype.org/impress/pipeline/1000007 or https://api.mousephenotype.org/impress/pipeline/bykey/ALTIMPC_001