OData (Open Data Protocol)

Some parts of the REST API expose collections which can be queried via OData mechanisms.

ODATA, or Open Data Protocol, is an involved standard allowing for adhoc filtering, paging (and much more) of resources - more details can be found here.

Currently Enterprise Tester leverages some features of OData as below:

• $filter - Is supported for OData implementing collections.
• $orderby - Is supported for OData implementing collections.
• $expand - Is supported for most resource types, but it's implementation differs in some ways (we align more closely with the Jira REST API expand functionality).
• $top - Is supported for OData implementing collections (also supported on any collections that take TQL queries).
• $skip - Is supported for OData implementing collections (also supported on any collections that take TQL queries).

Enterprise Tester at current does not intend to be OData compliant, in particular we have no plans to implement the navigation or metadata features that are within OData, at least not for the first version of the API.

Please see the Uri Conventions topic on the OData website for more information on how the various query parameters can be used to compose queries.

URL structure

Just to whet your appetite, here is a simple query of the projects collection - demonstrating projects being filtered, ordered and paged:

GET /api/projects?$filter=substringof('test',Name) eq true&$orderby=Name desc&$top=5

Pulling the URL apart we can see that:

• The filter is "substringof('test',Name) eq true" - this will find all projects containing the word 'test' ($filter = substringof('test',Name))
• we are sorting by the Name of the project, in descending order. ($order=Name desc)
• We want the first 5 resuts only ($top=5)

Examples

Example - Query without inline count

Url:

 http://myserver/EnterpriseTester/api/users?$filter=Name eq 'john'&$top=2

Results:

{
  "Items": [
    {
      "Id": "5b2b0ad0-5371-4abf-a661-9f410088925f",
      "UserName": "Administrator",
      "Email": "john.smith@mycompany.com",
      "FirstName": "John",
      "LastName": "Smith",
      "Self": "http://myserver/EnterpriseTester/api/user/5b2b0ad0-5371-4abf-a661-9f410088925f"
    },
    {
      "Id": "084c8a30-071c-4280-bf4c-9f48015b195f",
      "UserName": "johnb",
      "Email": "john.blogs@mycompany.com",
      "FirstName": "John",
      "LastName": "Bloggs",
      "Self": "http://myserver/EnterpriseTester/api/user/084c8a30-071c-4280-bf4c-9f48015b195f"
    }
}

Example - Query with inline count

Url:

http://myserver/EnterpriseTester/api/users?$inlinecount=allpages&$top=2&$skip=3

Results:

{
    "Skip": 3,
    "Top": 2,
    "Total": 497,
    "Items": [
        {
          "Id": "5b2b0ad0-5371-4abf-a661-9f410088925f",
          "UserName": "Administrator",
          "Email": "john.smith@mycompany.com",
          "FirstName": "John",
          "LastName": "Smith",
          "Self": "http://myserver/EnterpriseTester/api/user/5b2b0ad0-5371-4abf-a661-9f410088925f"
        },
        {
          "Id": "084c8a30-071c-4280-bf4c-9f48015b195f",
          "UserName": "johnb",
          "Email": "john.blogs@mycompany.com",
          "FirstName": "John",
          "LastName": "Bloggs",
          "Self": "http://myserver/EnterpriseTester/api/user/084c8a30-071c-4280-bf4c-9f48015b195f"
        }
    ]
}