Versioning

The API is currently at version 1.0. All API endpoints (other than authentication) require you to specify the API version as part of the path.

URL Paths

Authentication requests should be made to /auth/signin, as documented below. All other API requests should be made to sub-paths of /rp/api/1.0/....

Authentication

API requests are authenticated using an OAuth Bearer token. You can get a token by authenticating your user by sending a POST request to /auth/signin, with "username and "password" parameters form-encoded in the body of the request. POST /auth/signin HTTP/1.1 Content-Type: application/x-www-form-urlencoded username=user@example.com&password=some-secret-password

The response will be a JSON object including both "access_token" and "refresh_token" property. All other requests against the Bench API should include an authorization header: Authorization: Bearer xxxYYYzzz, where xxxYYYzzz is the value of "access_token" in the response.

For example: $ curl https://bench.gobridgit.com/auth/signin -H 'Content-Type: application/x-www-form-urlencoded' --data-urlencode 'username=someone@example.com' --data-urlencode 'password=[...snip...]' { "access_token": "...snip...", "token_type": "Bearer", "refresh_token": "...snip..." "expiry": "2020-01-01T00:00:00.413440849Z" }

The refresh token can be used to generate new session by request with /auth/token endpoint: POST /auth/token HTTP/1.1 Content-Type: application/x-www-form-urlencoded grant_type=refresh_token&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA

Note that once the refresh token is used, the previous access and refresh token is no longer valid.

For example: $ curl https://bench.gobridgit.com/auth/token -H 'Content-Type: application/x-www-form-urlencoded' --data-urlencode 'grant_type=refresh_token' --data-urlencode 'refresh_token=[...snip...]' { "access_token": "...snip...", "token_type": "Bearer", "refresh_token": "...snip..." "expiry": "2020-01-01T00:00:00.413440849Z" }

Pagination

Several of the API endpoints are paginated. These are denoted by including the offset (zero-based offset) and limit query parameters. For example, to request the 10 items, set the offset=0 to limit=10.
NOTE: the result set contains items with index of 0-9
To request the next 10 items (starting at index 10), set the offset=10 to limit=10

Responses to paginated API endpoints return a JSON array of objects. If there are results beyond the page you have requested, the server will set a query-has-more: true header in the response.

Request Encoding

GET and DELETE requests should have parameters encoded as URL query parameters. Boolean values should be encoded as true and false, not as 1 and 0.

Errors

Errors are returned for some response codes such as 400 Bad Request in the following format: { "errors": [ { "errorType": "ValidationError", "description": "The value of Name must be a string with a minimum length of 1 and a maximum length of 8 and not whitespace.", "field": "Name", "values": [ null ] } ], "title": "One or more validation errors occurred.", "status": 400, "instance": "api/v1/accounts/0/persons", "requestUid": "123e4567-e89b-12d3-a456-426614174000" }