Rosie Web API§

This section explains how to use the Rosie web service API. All Rosie discovery services (e.g. rosie search, rosie go, web page) use a RESTful API to interrogate a web server, which then interrogates an RDBMS. Returned data is encoded in the JSON format.

Location§

The URLs to access the web API of a Rosie web service (with a given prefix name) can be found in your Rose site configuration file as the value of [rosie-id]prefix-ws.PREFIX_NAME. To access the API for a given repository with prefix PREFIX_NAME, you must select a format (the only currently supported format is JSON) and use a url that looks like:

http://host/<PREFIX_NAME>/get_known_keys?format=json

REST API§

GET (str: prefix)/get_known_keys

Return the main property names stored for suites (e.g. idx, branch, owner) plus any additional names specified in the site config.

Parameters:	prefix (str) – Repository prefix. format (string) – Desired return format (json or None).

Example Request

GET http://host/my_prefix/get_known/keys?format=json HTTP/1.1

Example Response

["access-list", "idx", "branch", "owner", "project", "revision", "status",  "title"]

GET (str: prefix)/get_optional_keys

Return all unique optional or user-defined property names given in suite discovery information.

Parameters:	prefix (str) – Repository prefix. format (string) – Desired return format (json or None).

Example Request

GET http://host/my_prefix/get_optional_keys?format=json HTTP/1.1

Example Response

["access-list", "description", "endgame_status", "operational_flag", "tag-list"]

GET (str: prefix)/get_query_operators

Returns all the SQL-like operators used to compare column values that you may use in GET (str:prefix)/query (e.g. eq, ne, contains, like).

Parameters:	prefix (str) – Repository prefix. format (string) – Desired return format (json or None).

Example Request

GET http://host/my_prefix/get_query_operators?format=json HTTP/1.1

Example Response

["eq", "ge", "gt", "le", "lt", "ne", "contains", "endswith", "ilike", "like", "match", "startswith"]

GET (str: prefix)/query

Return a list of suites matching all search terms.

Parameters:	prefix (str) – Repository prefix. query (list) – List of queries. format (string) – Desired return format (json or None). all_revs (flag) – Switch on searching older revisions of current suites and deleted suites.
Query Parameters:
	CONJUNCTION (str) – and or or. OPEN_GROUP (str) – optional, one or more (. FIELD (str) – e.g. idx or description. OPERATOR (str) – e.g. contains or between, one of the operators returned by GET (str:prefix)/get_query_operators. VALUE (str) – e.g. euro4m or 200. CLOSE_GROUP (str) – optional, one or more ).

Query Format

CONJUNCTION+[OPEN_GROUP+]FIELD+OPERATOR+VALUE[+CLOSE_GROUP]

The first CONJUNCTION is technically superfluous. The OPEN_GROUP and CLOSE_GROUP do not have to be used.

Parentheses can be used in the query to group expressions.

Example Request

Return all current suites that have an idx that ends with 78 and also all suites that have the owner bob.

GET http://host/my_prefix/query?q=and+idx+endswith+78&q=or+owner+eq+bob&format=json HTTP/1.1

Example Response

Each suite is returned as an entry in a list - each entry is an associative array of property name-value pairs.

[{"idx": "mo1-aa078", "branch": "trunk", "revision": 200, "owner": "fred",
  "project": "fred's project.", "title": "fred's awesome suite",
  "status": "M ", "access-list": ["fred", "jack"], "description": "awesome"},
 {"idx": "mo1-aa090", "branch": "trunk", "revision": 350, "owner": "bob",
  "project": "var", "title": "A copy of var.vexcs.", "status": "M ",
  "access-list": ["*"], "operational": "Y"}]

GET (str: prefix)/search

Return a list of suites matching one or more search terms.

Parameters:	prefix (str) – Repository prefix. search (list) – List of queries in the same format as GET (str:prefix)/query format (string) – Desired return format (json or None). all_revs (flag) – Switch on searching older revisions of current suites and deleted suites.

Example Request

Return suites which match var, bob or nowcast.

GET http://host/my_prefix/search?var+bob+nowcast&format=json HTTP/1.1

Example Response

[{"idx": "mo1-aa090", "branch": "trunk", "revision": 330, "owner": "bob",
  "project": "um", "title": "A copy of um.alpra.", "status": "M ",
  "description": "Bob's UM suite"},
 {"idx": "mo1-aa092", "branch": "trunk", "revision": 340, "owner": "jim",
  "project": "var", "title": "6D Quantum VAR.", "status": "M ",
  "location": "NAE"},
 {"idx": "mo1-aa100", "branch": "trunk", "revision": 352, "owner": "ops_account",
  "project": "nowcast", "title": "The operational Nowcast suite",
  "status": "M ", "ensemble": "yes"}]

Python API§

The REST API maps onto the Python RosieWSClient back-end which can be used as a standalone Python API.

class rosie.ws_client.RosieWSClient(prefixes=None, prompt_func=None, popen=None, event_handler=None)

A client for the Rosie web service.

Parameters:

prefixes (list) – List of prefix names as strings. (run rose config rosie-id for more info). prompt_func (function) – Optional function for requesting user credentials. Takes and returns the arguments username and password. popen (rose.popen.RosePopener) – Use initiated RosePopener instance create a new one if None. event_handler (object) – A callable object for reporting popen output, see rose.reporter.Reporter.

address_lookup(**kwargs)

Repeat a Rosie query or search by address.

get_known_keys()

Return the known query keys.

get_optional_keys()

Return the optional query keys.

get_query_operators()

Return the query operators.

hello(return_ok_prefixes=False)

Ask the server to say hello.

query(q, **kwargs)

Query the Rosie database.

query_local_copies(user=None)

Returns details of the local suites.

As if they had been obtained using a search or query.

classmethod query_split(args)

Split a list of arguments into a list of query items.

search(s, **kwargs)

Search the Rosie database for a matching string.

set_prefixes(prefixes)

Replace the default prefixes.

Parameters:	prefixes (list) – List of prefix names as strings.