Guidelines

Available as RESTful JSON (except authentication which uses OAuth), the PhlexTMF API is used to manage the manipulation of objects and their values within the system.

The API is designed to work with the OpenAPI v2.0 specification. This is versioned using Semantic Versioning 2.0.0 and APIs follow this versioning approach.

HTTP Verbs

Standard HTTP verbs are to be used to indicate the intent of a request.

• GET – Retrieve a resource or a collection of resources
• POST – Create a resource, or retrieve a collection of resources using complex filters (see URL Length below)
• PUT – Update a resource
• DELETE – Delete a resource

Common functionality

Pagination

By default, collection endpoints with filters and pagination support return only the first 100 items. To get a different set of items, use the offset and and limit parameters in the query string; limit should not exceed that of server limit.

For example:

GET /v5/Documents returns documents 1-100
GET /v5/Documents/?limit=50 returns documents 1-50
GET /v5/Documents/?offset=20&limit=30 returns documents 21-50
GET /v5/Documents/?offset=40 returns documents 41-140

Use the “paging” section of the JSON response to get the total number of items in the totalItemCount parameter, then send subsequent requests with increasing offsets and a fixed limit until you get all the data.

For example if your first request is …/Documents?offset=0&limit=25, and the response includes totalItemCount: 100, continue with the calls:

…/Documents?offset=25&limit=25
…/Documents?offset=50&limit=25
…/Documents?offset=75&limit=25

Nested/embedded collections are not paged

Sorting

Sorting of data must support multiple-field based sorting of resources with an optional direction via the orderby parameter. For example:

GET v5/milestones?orderby=name asc,description desc

Filtering

Filtering of collections must use the filter parameter. This consists of a series of expressions which can be grouped with a grouping operator () to control the evaluation order.

Filter Types

• string – enclosed in single quote characters
• number
• date – enclosed in single quote characters and provided in yyyy-mm-dd format unless system configuration requires otherwise

Filter Operators

Operator

Description

Examples

Comparison Operators

eq

Equal. Applies to strings, dates, numbers.

name eq 'John Smith’

ne

Not equal. Applies to strings, dates, numbers.

company ne 'Phlexglobal'

gt

Greater than. Applies to dates, numbers only.

pagecount gt 20

ge

Greater than or equal. Applies to dates, numbers only.

pagecount ge 10

lt

Less than. Applies to dates, numbers only.

pagecount lt 20

le

Less than or equal. Applies to dates, numbers only.

pagecount le 100

in

In. Apples to strings, dates, numbers.

company in ('Phlexglobal', 'NSE')

Logical Operators

and

Logical and

pagecount le 200 and pagecount gt 20

or

Logical or

pagecount le 20 or pagecount gt 200

Note: this can't be used with the Documents API.

not

Logical negation

not pagecount le 35

Functional Operators

contains

Contains (like). Applies to strings only.

contains(protocol, 'test')

startswith

Starts with. Applies to strings only.

startswith(protocol, 'test')

endswith

Ends with. Applies to strings only.

endswith(protocol, 'test')

Grouping Operators

( )

Precedence grouping

(priority eq 1 or company eq 'Phlexglobal') and pagecount gt 20

date gt '2016-04-20' and protocol eq 'PG-001'

protocol eq 'PG-001' and site eq '0001'

Rate limiting/thresholds

There is currently no limit to the number of requests a user can make.

URL Length

Due to compatibility issues, URLs over 2000 characters long must be avoided. Any received request longer than 2000 must respond with a 414 (URI Too Long) status code. If you need multiple values for multiple filters of varying length (such as for document searching) use the POST verb in preference to a GET to avoid potentially exceeding the URL length.