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 (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 – Repository prefix.

  • format – 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 (prefix)/get_optional_keys

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

Parameters:

  • prefix – Repository prefix.

  • format – 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 (prefix)/get_query_operators

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

Parameters:

  • prefix – Repository prefix.

  • format – 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 (prefix)/query

Return a list of suites matching all search terms.

Parameters:

  • prefix – Repository prefix.

  • q – List of queries.

  • format – Desired return format (json or None).

  • all_revs – Switch on searching older revisions of current suites and deleted suites.

Query Parameters:

  • CONJUNCTION – and or or.

  • OPEN_GROUP – optional, one or more (.

  • FIELD – e.g. idx or description.

  • OPERATOR – e.g. contains or between, one of the operators returned by GET (prefix)/get_query_operators.

  • VALUE – e.g. euro4m or 200.

  • CLOSE_GROUP – 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"}]

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

Parameters:

  • prefix – Repository prefix.

  • s – List of queries in the same format as GET (prefix)/query

  • format – Desired return format (json or None).

  • ll_revs – 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/?s=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"}]