REST API Documentation - WHOIGit/ooicgsn-roundabout GitHub Wiki
Using the Roundabout REST API
Current Version: v1
The RDB REST API is versioned, all requests to the API follow this structure:
https://your-rdb-domain.com/api/v1/. The API is available as of Roundabout v1.6.
Schema
All API access is over HTTPS, and all data is sent and received as JSON.
Authorization
There are two ways to authenticate to the RDB API.
- Basic authentication using your username/password. This is generally useful for browsing the API via web browser, and is not recommended for production use.
- Token authentication. All registered RDB users can get a Token to access the API. You can access this token through your user profile in the RDB web site, or by making a direct request to the server. The API will return a JSON response with your token when valid
usernameandpasswordfields are POSTed to this endpoint using form data or JSON:https://your-rdb-domain.com/api/v1/api-token-auth/
For clients to authenticate, the token key should be included in the Authorization HTTP header. The key should be prefixed by the string literal "Token", with whitespace separating the two strings. For example:
Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b
Python Requests library ex:
r = requests.get('https://your-rdb-domain.com/api/v1/', headers={'Authorization': 'Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b'})
Root endpoint and browsable API
You can issue a GET request to the root endpoint to get links to all the resource categories that the API supports:
https://your-rdb-domain.com/api/v1/
If you access the API root in a web browser, you will get an HTML version of the API that you can browse through by using the hypermedia links for all resources. This is an excellent way to learn how the API works and explore the way RDB data is structured.
Hyperlinked resources
The RDB API is a "hypermedia" API. This means that all resources will have a url property that contains the URL for its endpoint, and all related fields will also contain a url property with links to all related resources. These are meant to provide explicit URLs so that API clients don't need to construct URLs on their own, and to make the API much easier to navigate and use.
The default API response for all resources is a detailed representation that includes all attributes for that resource. Example of standard "Inventory" resource response:
https://your-rdb-domain.com/api/v1/inventory/1035/
{
"id": 1035,
"url": "https://your-rdb-domain.com/api/v1/inventory/1035/",
"serial_number": "12991-03",
"old_serial_number": "12991-03",
"part": "https://your-rdb-domain.com/api/v1/part-templates/parts/936/",
"location": "https://your-rdb-domain.com/api/v1/locations/77/",
"revision": "https://your-rdb-domain.com/api/v1/part-templates/revisions/832/",
"parent": null,
"children": [],
"build": null,
"assembly_part": null,
"assigned_destination_root": null,
"created_at": "2020-03-18T21:19:09.146301Z",
"updated_at": "2020-03-18T21:23:39.147358Z",
"test_result": null,
"test_type": null,
"flag": false,
"time_in_field": "0 days 0 hours 0 min",
"calibration_events": [],
"actions": [
"https://your-rdb-domain.com/api/v1/actions/4041/",
"https://your-rdb-domain.com/api/v1/actions/4040/"
],
"fieldvalues": [
"https://your-rdb-domain.com/api/v1/user-defined-fields/field-values/784/"
],
"inventory_deployments": []
}
Dynamic loading of related resources
By default, the RDB API doesn't load any nested data for related resources, it instead provides the hyperlinks to all resources. This improves speed of API requests and eases the load on the RDB server as some of the tree structures in RDB can be especially resource intensive to retrieve. However, if a API user prefers to retrieve related data for a resource in a single request, they can user the expand keyword to request the API to load specific nested data structures. Using the previous example:
https://your-rdb-domain.com/api/v1/inventory/1035/?expand=part
{
"id": 1035,
"url": "https://your-rdb-domain.com/api/v1/inventory/1035/",
"serial_number": "12991-03",
"old_serial_number": "12991-03",
"part": {
"id": 936,
"url": "https://your-rdb-domain.com/api/v1/part-templates/parts/936/",
"name": "CE MMP Extended Version (MMP-7-EXT)",
"revisions": [
"https://your-rdb-domain.com/api/v1/part-templates/revisions/832/"
],
"part_type": "https://your-rdb-domain.com/api/v1/part-templates/part-types/4/",
"friendly_name": "CE McLane MMP",
"part_number": "3310-0003-00005",
"unit_cost": "0.00",
"refurbishment_cost": "0.00",
"note": "",
"user_defined_fields": [
"https://your-rdb-domain.com/api/v1/user-defined-fields/fields/18/",
"https://your-rdb-domain.com/api/v1/user-defined-fields/fields/20/"
],
"cal_dec_places": 0,
"coefficient_name_events": [],
"coefficient_names": []
},
"location": "https://your-rdb-domain.com/api/v1/locations/77/",
"revision": "https://your-rdb-domain.com/api/v1/part-templates/revisions/832/",
"parent": null,
"children": [],
"build": null,
"assembly_part": null,
"assigned_destination_root": null,
"created_at": "2020-03-18T21:19:09.146301Z",
"updated_at": "2020-03-18T21:23:39.147358Z",
"test_result": null,
"test_type": null,
"flag": false,
"time_in_field": "0 days 0 hours 0 min",
"calibration_events": [],
"actions": [
"https://your-rdb-domain.com/api/v1/actions/4041/",
"https://your-rdb-domain.com/api/v1/actions/4040/"
],
"fieldvalues": [
"https://your-rdb-domain.com/api/v1/user-defined-fields/field-values/784/"
],
"inventory_deployments": []
}
Multiple related resources can be expanded by separating field names with a comma: ?expand=part,location,children
You can use dot notation to expand deeply nested resources as well:
https://your-rdb-domain.com/api/v1/inventory/1035/?expand=part.part_type
{
"id": 1035,
"url": "https://your-rdb-domain.com/api/v1/inventory/1035/",
"serial_number": "12991-03",
"old_serial_number": "12991-03",
"part": {
"id": 936,
"url": "https://your-rdb-domain.com/api/v1/part-templates/parts/936/",
"name": "CE MMP Extended Version (MMP-7-EXT)",
"revisions": [
"https://your-rdb-domain.com/api/v1/part-templates/revisions/832/"
],
"part_type": {
"id": 4,
"url": "https://your-rdb-domain.com/api/v1/part-templates/part-types/4/",
"name": "Instrument",
"parent": null,
"children": [
"https://your-rdb-domain.com/api/v1/part-templates/part-types/6/"
],
} etc.
You can set expand=~all to automatically expand all fields that are available for expansion. This will take effect only for the top-level fields; if you need to also expand fields that are present on deeply nested models, then you will need to explicitly pass their values using dot notation.
Dynamic setting of fields (Sparse Fields)
To further improve client performance, you can use either the fields or omit keywords to declare only the fields you want to include or to specify fields that should be excluded.
For example: https://your-rdb-domain.com/api/v1/inventory/1035/?fields=id,serial_number
{
"id": 1035,
"serial_number": "12991-03"
}
Filtering of API Results
The RDB API allows almost any top-level field in a resource to be used as a search filter to limit the results returned. The best way to see all filters available for each resource is to use the browsable API and click on the Filters button to see the resulting url query parameters that are created for each filter. A basic example would look like this:
https://your-rdb-domain.com/api/v1/inventory/?serial_number=2222-3333-4444-20001
This would return all Inventory resources that match that serial number.
General filtering rules:
- All text field filters in RDB use the "contain" search type by default.
- All related resources can be filtered by their Primary Key id -
?fieldname=1- and by afieldname__is_nullboolean filter - Some related resources can also be filtered by specific nested fields. For example, Inventory can be be filtered by Part Number as well as the Part id. These nested filters use the double underscore notation, ex:
?part__part_number=1234-1234 - All date fields can be filtered by both date match and a range. So for a date field such as
created_at, you could filter by bothcreated_atusing the day you want to match or by thecreated_at__range_afterandcreated_at__range_beforeparameters. Ex date format:https://your-rdb-domain.com/api/v1/inventory/?created_at=2019-08-07 - Several RDB resources have a tree structure with "parent"/"children" fields. Any resource that has this tree structure also has some special filters:
is_rootwill limit the results to only top level items in the treehas_childrenwill limit the results to only items that have children- Ex. to get all root Locations:
https://your-rdb-domain.com/api/v1/locations/?is_root=true - Ex. to get all Inventory items that are the root of an assembly:
https://your-rdb-domain.com/api/v1/inventory/?is_root=true&has_children=true
- The Inventory resource has filter shortcuts for filtering by the Custom Fields that can be defined by users. These shortcuts are simply:
field_value=stringfield_name=string
Pagination
The RDB API is paginated and returns 30 results per page. The Link header includes pagination information, ex:
Link: <https://your-rdb-domain.com/api/v1/inventory/?page=2>; rel="next", <https://your-rdb-domain.com/api/v1/inventory/?page=102>; rel="last"
This Link response header contains one or more Hypermedia link relations, the possible rel values are: "next", "last", "first", "prev". For more information on traversing paginated results, follow the Github API guidelines. Using Python Requests:
response.links
Returns dictionary of links header value which can parsed further:
response.links.get('next')
Resources
The RDB API was built using the Django REST Framework and the following third-party packages: