run.coffee

#!/usr/bin/env coffee
http = require 'http'

# Which mine?
mine = 'http://beta.flymine.org/beta'

# Replace multiple whitespace with a single space.
clean = (text) -> text.replace(/\s+/g, ' ')

# Get the services listing.
http.get("#{mine}/service", (res) ->
  chunks = []
  
  # Chunks.
  res.on 'data', (chunk) -> chunks.push chunk
  
  # Chunk end.
  res.on 'end', ->
    console.log "#Services available on [#{mine}](#{mine})\n"
    # For each endpoint.
    for x, i in (arr = JSON.parse(Buffer.concat(chunks)).endpoints)
        console.log """
        ###{x.name}\n
        """

        # Some endpoints do not have methods.
        console.log "####GET [#{x.URI}](#{mine}#{x.URI})\n" unless x.methods.length

        # List the methods.
        for m in x.methods
            auth = if m.RequiresAuthentication then '(auth)' else ''

            console.log "#####{m.HTTPMethod} [#{x.URI}](#{mine}#{x.URI}) #{auth}\n"
            console.log "*#{clean(m.Synopsis)}*\n" if m.Synopsis
            console.log "#{clean(m.Description)}\n" if m.Description

            do ->
                return unless m.parameters.length
                console.log """
                Parameter | Default | Type | Required | Description
                --- | --- | --- | --- | ---
                """
                # For each param.
                for p in m.parameters
                    req = if p.Required is 'Y' then 'Yes' else 'No'
                    def = if p.Default then "`#{p.Default}`" else ''
                    console.log "`#{p.Name}` | #{def} | #{p.Type} | #{req} | #{p.Description}"
                console.log ''

        console.log '---\n' unless i + 1 is arr.length

# Trouble.
).on 'error', (err) ->
    throw err

services.md

#Services available on http://beta.flymine.org/beta

##Query Results

####POST /service/query/results (auth)

Get results for a query against the database.

This service provides full access to arbitrary database queries. Queries are accepted in a serialised XML format, executed and returned in a streaming manner. The query format is a custom subset of the capabilities of SQL; see the InterMine wiki for a full description of the query XML syntax.

Parameter	Default	Type	Required	Description
query		XML	Yes	A definition of the query to execute in Path-Query XML format
version	2	Integer	No	The version of the XML format used
start	0	Integer	No	The index of the first result to return.
size	10	Integer	No	The maximum size of the result set.
format	tab	enumerated	No	Output format

####GET /service/query/results (auth)

Get results for a query against the database.

This service provides full access to arbitrary database queries. Queries are accepted in a serialised XML format, executed and returned in a streaming manner. The query format is a custom subset of the capabilities of SQL; see the InterMine wiki for a full description of the query XML syntax.

Parameter	Default	Type	Required	Description
query		XML	Yes	A definition of the query to execute in Path-Query XML format
version	2	Integer	No	The version of the XML format used
start	0	Integer	No	The index of the first result to return.
size	10	Integer	No	The maximum size of the result set.
format	tab	enumerated	No	Output format

---

##Create List from Query

####POST /service/query/tolist (auth)

Save the result set of a query as a list on the server.

This service provides the facility to submit a query and create a new list whose contents shall be the result set defined by running the query. This facility places a couple of restrictions on the query itself, namely that the view list may only contain a single item, which should refer to the internal id attribute of an object in the query.

Parameter	Default	Type	Required	Description
query		XML	Yes	A definition of the query to execute in Path-Query XML format
listName		String	Yes	The name for the new list. There must be no existing list of this name
description		String	No	A description to attach to the new list
tags		String[]	No	A set of tags to use to categorise the new list
format	json	enumerated	No	Output format

####GET /service/query/tolist (auth)

Save the result set of a query as a list on the server.

This service provides the facility to submit a query and create a new list whose contents shall be the result set defined by running the query. This facility places a couple of restrictions on the query itself, namely that the view list may only contain a single item, which should refer to the internal id attribute of an object in the query.

Parameter	Default	Type	Required	Description
query		XML	Yes	A definition of the query to execute in Path-Query XML format
listName		String	Yes	The name for the new list. There must be no existing list of this name
description		String	No	A description to attach to the new list
tags		String[]	No	A set of tags to use to categorise the new list
format	json	enumerated	No	Output format

---

##Add to List from Query

####POST /service/query/append/tolist (auth)

Add the result set of a query to a list on the server.

This service provides the facility to submit a query and add the objects contained in its result set to a list that already exists on the server. This facility places a couple of restrictions on the query itself, namely that the view list may only contain a single item, which should refer to the internal id attribute of an object in the query.

Parameter	Default	Type	Required	Description
query		XML	Yes	A definition of the query to execute in Path-Query XML format.
name		String	Yes	The list to append items to.
tags		String[]	No	A set of tags to use to categorise the new list
format	json	enumerated	No	Output format

####GET /service/query/append/tolist (auth)

Add the result set of a query to a list on the server.

This service provides the facility to submit a query and add the objects contained in its result set to a list that already exists on the server. This facility places a couple of restrictions on the query itself, namely that the view list may only contain a single item, which should refer to the internal id attribute of an object in the query.

Parameter	Default	Type	Required	Description
query		XML	Yes	A definition of the query to execute in Path-Query XML format.
name		String	Yes	The list to append items to.
tags		String[]	No	A set of tags to use to categorise the new list
format	json	enumerated	No	Output format

---

##Save Query

####POST /service/query/upload (auth)

Save queries to a user account on the server.

This service provides the facility to submit one or more queries and save it/them for future reference to a user account on the server.

Parameter	Default	Type	Required	Description
xml		XML	Yes	A definition of the query/ies to save in Path-Query XML format.
version		Integer	No	The version of the path-qeury format being used.
format	json	enumerated	No	Output format

####GET /service/query/upload (auth)

Save queries to a user account on the server.

This service provides the facility to submit one or more queries and save it/them for future reference to a user account on the server.

Parameter	Default	Type	Required	Description
xml		XML	Yes	A definition of the query/ies to save in Path-Query XML format.
version		Integer	No	The version of the path-qeury format being used.
format	json	enumerated	No	Output format

---

##Find Lists Containing an Object

####POST /service/listswithobject (auth)

Find lists on the server containing an object.

This service allows users to get back a list of lists that contain a given object, either defined by an internal ID, or looked up from stable identifiers. If the request does not authenticate to a user account, then only relevant public lists will be returned.

Parameter	Default	Type	Required	Description
publicId		String	No	A stable identifier that can be used to find the object.
id		Integer	No	The internal DB id (changes on each re-release).
type		String	No	The type of object (required if using a public id)
extraValue		String	No	An extra value to disambiguate objects
format	json	enumerated	No	Output format

####GET /service/listswithobject (auth)

Find lists on the server containing an object.

This service allows users to get back a list of lists that contain a given object, either defined by an internal ID, or looked up from stable identifiers. If the request does not authenticate to a user account, then only relevant public lists will be returned.

Parameter	Default	Type	Required	Description
publicId		String	No	A stable identifier that can be used to find the object.
id		Integer	No	The internal DB id (changes on each re-release).
type		String	No	The type of object (required if using a public id)
extraValue		String	No	An extra value to disambiguate objects
format	json	enumerated	No	Output format

---

##Append to List

####POST /service/lists/append (auth)

Add items to an existing list by identifiers

This service allows users to add new items to an existing list by uploading a set of identifiers. This is equivalent to creating a new list from a set of identifiers, and then performing the union operation on that list an existing one, if the resulant list replaced the existing list.

Parameter	Default	Type	Required	Description
name		String	Yes	The name of the list to append to
format	json	enumerated	No	Output format

---

##List Union

####POST /service/lists/union (auth)

Combine Two or More Lists through Union

This service allows users to create new lists which contain all the members contained in the set of input lists. The user must have access to all the input lists, but need not be the owner of any of them. A union of a single list with itself may be considered a copy.

Parameter	Default	Type	Required	Description
name		String	Yes	The name of the list to create
lists		String[]	Yes	The name of a source list
description		String	No	A description of this new list
tags		String[]	No	A set of tags to apply to the new list
format	json	enumerated	No	Output format

####GET /service/lists/union (auth)

Combine Two or More Lists through Union

This service allows users to create new lists which contain all the members contained in the set of input lists. The user must have access to all the input lists, but need not be the owner of any of them. A union of a single list with itself may be considered a copy.

Parameter	Default	Type	Required	Description
name		String	Yes	The name of the list to create
lists		String[]	Yes	The name of a source list
description		String	No	A description of this new list
tags		String[]	No	A set of tags to apply to the new list
format	json	enumerated	No	Output format

---

##List Subtraction

####POST /service/lists/subtract (auth)

Subtract one List From Another

This service allows users to create new lists which contain only those elements which are present in one set of lists, and none of those elements which are present in another set of lists. This is what is typically thought of as subtraction, or more technically, the asymmetric difference of two sets. The user must supply the names of the lists to be used as either the source lists or the subtraction lists, as well as details for the new list to be created. The user must have access to all the named lists, but need not be the owner of any of them.

Parameter	Default	Type	Required	Description
name		String	Yes	The name of the list to create
references		String[]	Yes	The name of a source list
subtract		String[]	Yes	The name of a list to exclude
description		String	No	A description of this new list
tags		String[]	No	A set of tags to apply to the new list
format	json	enumerated	No	Output format

####GET /service/lists/subtract (auth)

Subtract one List From Another

This service allows users to create new lists which contain only those elements which are present in one set of lists, and none of those elements which are present in another set of lists. This is what is typically thought of as subtraction, or more technically, the asymmetric difference of two sets. The user must supply the names of the lists to be used as either the source lists or the subtraction lists, as well as details for the new list to be created. The user must have access to all the named lists, but need not be the owner of any of them.

Parameter	Default	Type	Required	Description
name		String	Yes	The name of the list to create
references		String[]	Yes	The name of a source list
subtract		String[]	Yes	The name of a list to exclude
description		String	No	A description of this new list
tags		String[]	No	A set of tags to apply to the new list
format	json	enumerated	No	Output format

---

##List Intersection

####POST /service/lists/intersect (auth)

Combine Two or More Lists through Intersection

This service allows users to create new lists which contain only those items which are members of all the source lists. The user must have access to all the input lists, but need not be the owner of any of them. An intersection of a single list may be considered a copy.

Parameter	Default	Type	Required	Description
name		String	Yes	The name of the list to create
lists		String[]	Yes	The name of a source list, or multiple list names concatenated with a ';' separator.
description		String	No	A description of this new list
tags		String[]	No	A set of tags to apply to the new list
format	json	enumerated	No	Output format

---

##List Difference

####POST /service/lists/diff (auth)

Combine Two or More Lists through Difference

This service allows users to create new lists which only contain members which are not shared by an even number of lists (see: http://en.wikipedia.org/wiki/Symmetric_difference). The user must have access to all the input lists, but need not be the owner of any of them.

Parameter	Default	Type	Required	Description
name		String	Yes	The name of the list to create
lists		String[]	Yes	The name of a source list
description		String	No	A description of this new list
tags		String[]	No	A set of tags to apply to the new list
format	json	enumerated	No	Output format

---

##Lists

####GET /service/lists (auth)

Find lists on the server.

This service allows users to get back a list of lists that they have access to. The lists can be optionally be filtered on the server by name, thus returning just a single name, or if '*' wildcards are used, a subset of all lists.

Parameter	Default	Type	Required	Description
name		String	No	An optional filter by name.
format	json	enumerated	No	Output format

####POST /service/lists (auth)

Create a new list

This service allows users to add new items to an existing list by uploading a set of identifiers. This is equivalent to creating a new list from a set of identifiers, and then performing the union operation on that list an existing one, if the resulant list replaced the existing list.

Parameter	Default	Type	Required	Description
name		String	Yes	The name of the new list
type		String	Yes	The type of the list
extraValue		String	No	A disambiguating value (such as organism name)
format	json	enumerated	No	Output format

---

##List Renaming

####GET /service/lists/rename (auth)

Rename an Existing List

This service allows users to change the name of an existing list that they are the owner of.

Parameter	Default	Type	Required	Description
oldname		String	Yes	The current name of the list
newname		String	Yes	The name the list should have

####POST /service/lists/rename (auth)

Rename an Existing List

This service allows users to change the name of an existing list that they are the owner of.

Parameter	Default	Type	Required	Description
oldname		String	Yes	The current name of the list
newname		String	Yes	The name the list should have

---

##Template Upload

####POST /service/template/upload (auth)

Save a Template, or Overwrite an Existing One

This service allows users to save templates they have authored on the server, associated with their account. The templates once saved can be used as any other template query.

Parameter	Default	Type	Required	Description
xml		XML	Yes	One or more templates, serialised in XML format.
version	2	Integer	No	The version of the XML format
format	text	enumerated	No	Output format

####GET /service/template/upload (auth)

Save a Template, or Overwrite an Existing One

This service allows users to save templates they have authored on the server, associated with their account. The templates once saved can be used as any other template query.

Parameter	Default	Type	Required	Description
xml		XML	Yes	One or more templates, serialised in XML format.
version	2	Integer	No	The version of the XML format
format	text	enumerated	No	Output format

---

##Template Results

####GET /service/template/results (auth)

Get the results from running a template with a given set of parameters

Templates are predefined parameterised queries which may be run by supplying values and operators for the available editable constraints. To run a template, for example which has the following editable constraints: Then the user should supply the following parameters to run it with the default values: constraint1=Gene.symbol&op1=eq&value1=eve&constraint2=Gene.length&op2=gt&value2=1000 The value of the number used to identify each constraint is ignored - it must however be consistent for each parameter.

Parameter	Default	Type	Required	Description
name		String	Yes	The name of the template to run
?		String[]	Yes	One of a variable set of parameters used to supply constraint values
start	0	Integer	No	The index of the first result to return.
size	10	Integer	No	The maximum size of the result set.
format	tab	enumerated	No	Output format

####POST /service/template/results (auth)

Get the results from running a template with a given set of parameters

Templates are predefined parameterised queries which may be run by supplying values and operators for the available editable constraints. To run a template, for example which has the following editable constraints: Then the user should supply the following parameters to run it with the default values: constraint1=Gene.symbol&op1=eq&value1=eve&constraint2=Gene.length&op2=gt&value2=1000 The value of the number used to identify each constraint is ignored - it must however be consistent for each parameter.

Parameter	Default	Type	Required	Description
name		String	Yes	The name of the template to run
?		String[]	Yes	One of a variable set of parameters used to supply constraint values
start	0	Integer	No	The index of the first result to return.
size	10	Integer	No	The maximum size of the result set.
format	tab	enumerated	No	Output format

---

##Template to list

####GET /service/template/tolist (auth)

Create a List from the Output of a Template

This service allows the user to create a list from the result set of running a template with a given set of parameters. The parameters for running the template are the same as when requesting results, and in addition to these parameters the user needs to supply a name and optional description for the list to be created. To define which part of the template results, the user must supply a path parameter which indicates a valid column from the output to be used. Templates are predefined parameterised queries which may be run by supplying values and operators for the available editable constraints. To run a template, for example which has the following editable constraints: Then the user should supply the following parameters to run it with the default values: constraint1=Gene.symbol&op1=eq&value1=eve&constraint2=Gene.length&op2=gt&value2=1000 The value of the number used to identify each constraint is ignored - it must however be consistent for each parameter.

Parameter	Default	Type	Required	Description
name		String	Yes	The name of the template to run
path		String	Yes	The path to use to compose the results
?		String[]	Yes	One of a variable set of parameters used to supply constraint values
listName		String	Yes	The name for the new list. There must be no existing list of this name
description		String	No	A description to attach to the new list
tags		String[]	No	A set of tags to use to categorise the new list
format	json	enumerated	No	Output format

####POST /service/template/tolist (auth)

Create a List from the Output of a Template

This service allows the user to create a list from the result set of running a template with a given set of parameters. The parameters for running the template are the same as when requesting results, and in addition to these parameters the user needs to supply a name and optional description for the list to be created. To define which part of the template results, the user must supply a path parameter which indicates a valid column from the output to be used. Templates are predefined parameterised queries which may be run by supplying values and operators for the available editable constraints. To run a template, for example which has the following editable constraints: Then the user should supply the following parameters to run it with the default values: constraint1=Gene.symbol&op1=eq&value1=eve&constraint2=Gene.length&op2=gt&value2=1000 The value of the number used to identify each constraint is ignored - it must however be consistent for each parameter.

Parameter	Default	Type	Required	Description
name		String	Yes	The name of the template to run
path		String	Yes	The path to use to compose the results
?		String[]	Yes	One of a variable set of parameters used to supply constraint values
listName		String	Yes	The name for the new list. There must be no existing list of this name
description		String	No	A description to attach to the new list
tags		String[]	No	A set of tags to use to categorise the new list
format	json	enumerated	No	Output format

---

##Append to List from Template Results

####POST /service/template/append/tolist (auth)

Add items to a list from a set of results from running a template

This service allows the user to add items to a list from the result set of running a template with a given set of parameters. The parameters for running the template are the same as when requesting results, and in addition to these parameters the user needs to supply a name and optional description for the list to be created. To define which part of the template results, the user must supply a path parameter which indicates a valid column from the output to be used. Templates are predefined parameterised queries which may be run by supplying values and operators for the available editable constraints. To run a template, for example which has the following editable constraints: Then the user should supply the following parameters to run it with the default values: constraint1=Gene.symbol&op1=eq&value1=eve&constraint2=Gene.length&op2=gt&value2=1000 The value of the number used to identify each constraint is ignored - it must however be consistent for each parameter.

Parameter	Default	Type	Required	Description
name		String	Yes	The name of the template to run
path		String	Yes	The path to use to compose the results
?		String[]	Yes	One of a variable set of parameters used to supply constraint values
listName		String	Yes	The name of the list to add items to.
format	json	enumerated	No	Output format

####GET /service/template/append/tolist (auth)

Add items to a list from a set of results from running a template

This service allows the user to add items to a list from the result set of running a template with a given set of parameters. The parameters for running the template are the same as when requesting results, and in addition to these parameters the user needs to supply a name and optional description for the list to be created. To define which part of the template results, the user must supply a path parameter which indicates a valid column from the output to be used. Templates are predefined parameterised queries which may be run by supplying values and operators for the available editable constraints. To run a template, for example which has the following editable constraints: Then the user should supply the following parameters to run it with the default values: constraint1=Gene.symbol&op1=eq&value1=eve&constraint2=Gene.length&op2=gt&value2=1000 The value of the number used to identify each constraint is ignored - it must however be consistent for each parameter.

Parameter	Default	Type	Required	Description
name		String	Yes	The name of the template to run
path		String	Yes	The path to use to compose the results
?		String[]	Yes	One of a variable set of parameters used to supply constraint values
listName		String	Yes	The name of the list to add items to.
format	json	enumerated	No	Output format

---

##Templates

####GET /service/templates (auth)

Get the list of available templates.

Get a listing of the templates configured in an InterMine instance. Each template contains a description of its properties, defining the parameters that must be provided to run it, as well as a definition of the output format for its results. If the request is authenticated to a user, then the templates that that has access to will also be returned.

Parameter	Default	Type	Required	Description
includeBroken	false	boolean	No	Whether or not to include invalid templates. Invalid templates cannot be run.
format	xml	enumerated	No	Output format

####POST /service/templates (auth)

Upload one or more templates.

Upload a set of templates to the current user profile.

Parameter	Default	Type	Required	Description
includeBroken	false	boolean	No	The xml to load, if using form parameters.
format	xml	enumerated	No	Output format

---

##Data Model

####GET /service/model (auth)

Get a description of the data model

An InterMine data model can be fully described as a set of classes with various properties. This data model is useful for constructing queries and interpreting the results returned from the service.

Parameter	Default	Type	Required	Description
format	xml	enumerated	No	Output format

---

##Web-Service Version

####GET /service/version (auth)

Get the Web-Service Version.

Get the web-service version number. This number is incremented for each change in functionality.

Parameter	Default	Type	Required	Description
format	text	enumerated	No	Output format

####GET /service/version (auth)

Get the Data-Warehouse Release Version.

Get the release version of the data-warehouse. This is a string that is changed each time data is added or removed from the server. Thus this number is meant to reflect the contents rather than the interface of this set of services.

Parameter	Default	Type	Required	Description
format	text	enumerated	No	Output format

---

##ws-check-resource

####GET /service/check

---

##Possible Values

####GET /service/path/values (auth)

Get the possible values a path may have.

This service provides the possible values that a path may represent in the database. This functionality is expected to primarily useful for applications providing completion and suggestions for user-input.

Parameter	Default	Type	Required	Description
path		String	Yes	The path whose possible values are requested
typeConstraints		JSON	No	A json object mapping which describes the type constraints on this path
format	json	enumerated	No	Output format

####POST /service/path/values (auth)

Get the possible values a path may have.

This service provides the possible values that a path may represent in the database. This functionality is expected to primarily useful for applications providing completion and suggestions for user-input.

Parameter	Default	Type	Required	Description
path		String	Yes	The path whose possible values are requested
typeConstraints		JSON	No	A json object mapping which describes the type constraints on this path
format	json	enumerated	No	Output format

---

##ws-schemata

####GET /service/schema

---

##Summary Fields

####GET /service/summaryfields (auth)

Get the fields used to summarise the class

Parameter	Default	Type	Required	Description
norefs	false	Boolean	No	Whether to exclude references from the summary fields

---

##Generated Code

####GET /service/query/code (auth)

Get the code to run a pathquery in a given language.

This service provides the ability to generate code in one of several languages based on a pathquery provided in serialised form.

Parameter	Default	Type	Required	Description
lang	py	enumerated	Yes	The language to generate code in.
query		XML	Yes	The query to generate code for, in XML form.
format	text	enumerated	No	Output format

####POST /service/query/code (auth)

Get the code to run a pathquery in a given language.

This service provides the ability to generate code in one of several languages based on a pathquery provided in serialised form.

Parameter	Default	Type	Required	Description
lang	py	enumerated	Yes	The language to generate code in.
query		XML	Yes	The query to generate code for, in XML form.
format	text	enumerated	No	Output format

---

##List Tags

####GET /service/list/tags (auth)

Get the tags for a list, or all the tags for a given user

Fetch an up-to-date list of all tags associated with a list, or all lists.

Parameter	Default	Type	Required	Description
name		String	No	The name of a list whose tags to retrieve. If no list is provided, then all the tags associated with the authenticating user will be returned.
format	json	enumerated	No	Output format

####POST /service/list/tags (auth)

Add one or more tags to a list

Parameter	Default	Type	Required	Description
name		String	Yes	The name of a list to add the tag(s) to.
tags		String	Yes	The name of the tags to add. It should take to from of a semi-colon delimited concatenation of the tag names.
format	json	enumerated	No	Output format

####DELETE /service/list/tags (auth)

Delete one or more tags from a list

Parameter	Default	Type	Required	Description
name		String	Yes	The name of a list to add the tag(s) to.
tags		String	Yes	The name of the tags to remove. It should take to from of a semi-colon delimited concatenation of the tag names.
format	json	enumerated	No	Output format

---

##Widgets

####GET /service/widgets (auth)

Get a list of the widgets available at a service

This service returns a list of the widgets that are available at a given service. Each entry for the widget includes details of its type, the kind of data it processes, and any filters it accepts.

Parameter	Default	Type	Required	Description
format	json	enumerated	No	Output format

---

##Enrichment Widgets

####GET /service/list/enrichment (auth)

get the data for a given enrichment widget

Enrichment widgets provide a statistical summary of what makes a list distinct from the background population over a certain domain. They return a list of members of the domain ranked by p-value (low to high).

Parameter	Default	Type	Required	Description
list		String	Yes	The name of the list to investigate
widget		String	Yes	The name of the enrichment widget to display
population		String	No	The name of the list to use as the background population
maxp	0.05	Float	Yes	The maximum p-value of results to display. The range is 0.0 - 1.0
correction	Holm-Bonferroni	enumerated	Yes	The error correction algorithm to use.
filter		String	No	An optional filter that some widgets accept
format	json	enumerated	No	Output format

####POST /service/list/enrichment (auth)

get the data for a given enrichment widget

Enrichment widgets provide a statistical summary of what makes a list distinct from the background population over a certain domain. They return a list of members of the domain ranked by p-value (low to high).

Parameter	Default	Type	Required	Description
list		String	Yes	The name of the list to investigate
widget		String	Yes	The name of the enrichment widget to display
population		String	No	The name of the list to use as the background population
maxp	0.05	Float	Yes	The maximum p-value of results to display. The range is 0.0 - 1.0
correction	Holm-Bonferroni	enumerated	Yes	The error correction algorithm to use.
filter		String	No	An optional filter that some widgets accept
format	json	enumerated	No	Output format

---

##Graphical Widgets

####GET /service/list/chart (auth)

get the data to produce a graph

This service returns data that can be passed to charting software, such as Google's javascript Charts API, to produce graphical representations of the overview of data in a list.

Parameter	Default	Type	Required	Description
list		String	Yes	The name of the list to use as the population for the graph
widget		String	Yes	The name of the graphical widget to display
filter		String	No	An optional filter that some widgets accept
format	json	enumerated	No	Output format

####POST /service/list/chart (auth)

get the data to produce a graph

This service returns data that can be passed to charting software, such as Google's javascript Charts API, to produce graphical representations of the overview of data in a list.

Parameter	Default	Type	Required	Description
list		String	Yes	The name of the list to use as the population for the graph
widget		String	Yes	The name of the graphical widget to display
filter		String	No	An optional filter that some widgets accept
format	json	enumerated	No	Output format

---

##Table Widgets

####GET /service/list/table (auth)

Get the data as displayed by a table widget

This service returns data to produce a table representations of the overview of data in a list.

Parameter	Default	Type	Required	Description
list		String	Yes	The name of the list to use as the population for the graph
widget		String	Yes	The name of the graphical widget to display
format	json	enumerated	No	Output format

####POST /service/list/table (auth)

Get the data as displayed by a table widget

This service returns data to produce a table representations of the overview of data in a list.

Parameter	Default	Type	Required	Description
list		String	Yes	The name of the list to use as the population for the graph
widget		String	Yes	The name of the graphical widget to display
format	json	enumerated	No	Output format

---

##Report Widgets

####GET /service/widget/report (auth)

get the Report Widget JavaScript package

Parameter	Default	Type	Required	Description
id		String	Yes	The name of the widget to use
callback		String	Yes	The callback to use in the widget
format	json	enumerated	No	Output format

---

##QuickSearch

####GET /service/search (auth)

Perform a key-word search and retrieve the results

Run a general key-word style search over all data in the data-warehouse. Rather than a structured query for a specific type of data, this allows the user to search broadly over a range of data types, and use facetting information to restrict the search results.

Parameter	Default	Type	Required	Description
q		String	No	The query string to search with. If absent, or blank, all results will be returned
size	10	int	No	The maximum number of records to return. If no limit is provided, all results will be returned.
start	0	int	No	The index of the first result to return.
list		String	No	A list to search within.

####POST /service/search (auth)

Perform a key-word search and retrieve the results

Run a general key-word style search over all data in the data-warehouse. Rather than a structured query for a specific type of data, this allows the user to search broadly over a range of data types, and use facetting information to restrict the search results.

Parameter	Default	Type	Required	Description
q		String	No	The query string to search with. If absent, or blank, all results will be returned
size	10	int	No	The maximum number of records to return. If no limit is provided, all results will be returned.
start	0	int	No	The index of the first result to return.
list		String	No	A list to search within.

---

##Who-Am-I?

####GET /service/user/whoami (auth)

Get details about the authenticated user

Retrieve information about the currently authenticated user. This can be used to display the user's name.

---

##Token

####GET /service/user/token (auth)

Get a new API key

This service allows a user to retrieve an API token which is valid for up to 24 hours of unlimited use. The primary use case is to get an API key where the user has only username/password credentials, since the use of API keys is more secure.

---

##Users

####POST /service/users

Create a new user in the user-profile

This service allows users of the web service to create a new user account. A user account is required for a number of operations, such as saving lists. This service allows users of the webservice to register an account, and start using these features that require authentication. The username and password provided will be able to be used for future requests, as will an API key provided with the response, which is valid for 24 hours. This is equivalent to the registration mechanism in the web-application interface. Requests to this service are rate limited by IP Address

Parameter	Default	Type	Required	Description
name		Email	Yes	The user name of the new user. It should be an email address if possible. There must not be any user with the same username
password		String	Yes	A password to associate with the account.
subscribe-to-list		boolean	No	Whether or not to subscribe to the mine's mailing list, if it has one. The username must be an email address if true

---

##Key Fields

####GET /service/classkeys

Get the fields used to identify an object

Get the fields configured for this service to identify objects uniquely within the database.

---

##ID Resolution

####POST /service/ids (auth)

Start a New ID Resolution Job on the Server

New ID resolution jobs are created by posting a representation of the job to this service.

####GET /service/ids (auth)

Check the Status of a Given Job

Get a representation of the status of job.

Parameter	Default	Type	Required	Description
uid		String	Yes	The unique identifier of the job

####GET /service/ids (auth)

Get the Results of a Given Job

Get the full results of running a specific job.

Parameter	Default	Type	Required	Description
uid		String	Yes	The unique identifier of the job

####DELETE /service/ids (auth)

Delete a given job from the server.

Each job should be removed from the server when the user has finished inspecting the results.

Parameter	Default	Type	Required	Description
uid		String	Yes	The unique identifier of the job

---

##List Invitations

####POST /service/lists/invitations

Invite another user to share a list

Blah... todo

Parameter	Default	Type	Required	Description
list		String	Yes	The list of yours you wish to share
to		String	Yes	The email address of the user to invite to share a list.
send-emai		boolean	No	Whether or not to send an email to the invitee. The invitee value must be an email address if true

####GET /service/lists/invitations

Details of all outstanding invitations

This service returns a description of all the outstanding list invitations for a user on the system.

####GET /service/lists/invitations

Details of a single invitation

This service returns details of a single invitation on the system.

Parameter	Default	Type	Required	Description
uid		String	Yes	The identifier of the invitation - a 20 character unique string

####PUT /service/lists/invitations

Declare the acceptance of an invitation.

Blah... todo

Parameter	Default	Type	Required	Description
uid		String	Yes	The identifier of the invitation - a 20 character unique string
accepted		boolean	Yes	Whether or not this invitation is accepted or not.

---

##List Sharing

####POST /service/lists/shares

Authorise another user to access a list

This service provides a means for authorising another user to access a list. To share a list the user making the request must be the owner of the list and you must know the username of the user you wish to share with. If you do not know the username of the user to share with, then the user should issue an invitation instead. The user the list is shared with must exist and the list must not already be shared with them. The service returns information detailing whom the list in question is currently shared with.

Parameter	Default	Type	Required	Description
list		String	Yes	The list of yours you wish to share.
with		String	Yes	The username of the user who will have access.
notify		boolean	No	Whether or not to send an email to the user you are sharing with.

####GET /service/lists/shares

Retrieve information about which lists are shared with and by whom.

Get information about each list that is shared by or with the authenticating user. The service returns a map with two keys "sharedByUser" and "sharedWithUser" which are themselves each maps, with list names as keys, and either lists of users with access as values, or the name of the original owner as values.

####DELETE /service/lists/shares

Rescind the Permission Granted to a User to Access a List.

Stop a user from being able to access a list that you own. This service allows a user to remove a user's previously granted permission to view the contents of a list. Other than a json results envelope no meaningful results are returned, and the caller should simply check for a successful response.

---

##User Preferences

####POST /service/user/preferences

Set the value of one or more preferences

Thid service allows a user to store or change a key value pair associated with their account. The keys may have a particular meaning. All values will be stored and retrieved as strings.

Parameter	Default	Type	Required	Description
?		String[]	No	The preference to set

####GET /service/user/preferences

Get a user's preferences

Get a complete listing of a user's preferences. This is presented as a mapping from string key to string value.

####DELETE /service/user/preferences

Remove one or all preferences.

Delete either a single preference from a user's set of stored preferences, or deletes all stored preference values.

Parameter	Default	Type	Required	Description
key		String	No	The preference to delete. If not provided, ALL will be cleared

---

##Query Store

####GET /service/queries (auth)

Get a stored query

Get a query stored at the service.

Parameter	Default	Type	Required	Description
id		Integer	Yes	The id of the query to fetch

####POST /service/queries (auth)

Store a query

Parameter	Default	Type	Required	Description
query		String	Yes	The xml of the query to store.
format	json	enumerated	No	Output format

---

##Sequence Access

####GET /service/sequence (auth)

Get a portion of a sequence-like object

Get either the entire sequence of a character-sequence like thing, or fetch an indexed sub-sequence of it. This service expects a query with a single output column that resolves tp a sub-sequenceable object.

Parameter	Default	Type	Required	Description
start	0	Integer	No	The start index
end		Integer	No	The end index
query		String	Yes	The xml of the query to run.

---

##ws-jbrowse

####GET /service/jbrowse

---

##ws-deregistration-token

####GET /service/user/deregistration

---

##ws-user

####GET /service/user

---

##ws-perma-tokens

####GET /service/user/tokens

---

##ws-perma-token

####GET /service/user/tokens

---

##ws-branding

####GET /service/branding

---

##ws-saved-queries

####GET /service/user/queries

---

##ws-saved-template

####GET /service/templates

---

##Service Listing

####GET /service

Get a description of the services offered by this data-warehouse.