BrowZine Public API Overview

Summary

The Third Iron API provides access to some of the functionality that powers the BrowZine application to allow customers to better integrate their systems with BrowZine, including providing context-aware linking into BrowZine as well as surfacing BrowZine information within other systems.  It is a RESTful API, and so functions are accessed by submitting simple HTTP requests against the HTTP resources described in this document.  Access to the BrowZine API functions is governed through the use of OAuth 2 Bearer tokens, and API client request rates are limited as described in the Rate Limiting section to avoid inadvertent overloading of our system.  The API is available only over HTTPS to protect our customer's data and responses are all of Content-Type "application/json; charset=utf-8".

Auth

Our publicly available API accepts OAuth2 Bearer tokens to control access to functions and data of the API.   These tokens are valid for an indefinitely long period of time, although Third Iron may temporarily disable a token to protect our systems if we detect suspicious traffic.  Should we do so, Third Iron will notify your organization of the action taken and work with your team to resolve the issue.  If you believe that your token may be compromised and may be in use by unauthorized parties to access your organization's data, please contact our support team so we may revoke the compromised token and provide you with a new one for your application to use.

Registration and API token provisioning

To register your application for API use and request an API token, contact our support staff at support@thirdiron.com  

Use of API tokens:

In order to access API functions, your application will have to include the issued token on each request.  In conformance with the specification, you may:

1. Submit the token as part of an Authorization header as shown:

   Authorization: Bearer ffffffff-ffff-ffff-ffff-ffffffffffff

2. Submit the token as the access_token querystring parameter as shown:

   GET https://public-api.thirdiron.com/public/v1/get-some-data?access_token=ffffffff-ffff-ffff-ffff-ffffffffffff

Error responses

401

If your request fails to provide any token when making a request against a function that requires one, the API will respond with an HTTP 401 response with an WWW-Authenticate header specifying that the resource is expecting a bearer token.

Example:

HTTP/1.1 401 Unauthorized
X-Powered-By: Express
WWW-Authenticate: Bearer
Content-Type: application/json; charset=utf-8
Content-Length: 14
ETag: W/"e-285513e"
Vary: Accept-Encoding
Date: Wed, 08 Mar 2017 21:52:42 GMT
Connection: keep-alive


{"status":401}

If your request provides a token that is not recognized by the system (perhaps due to being reported as compromised and revoked), the API will respond with an HTTP 401 response with an WWW-Authenticate challenge header that reports an invalid_token error, with error_description holding additional information about why the submitted token is invalid and a response body that also contains the error and error_description.

Example:

HTTP/1.1 401 Unauthorized
X-Powered-By: Express
WWW-Authenticate: Bearer error="invalid_token", error_description="unknown_token"
Content-Type: application/json; charset=utf-8
Content-Length: 74
ETag: W/"4a-37cc998f"
Vary: Accept-Encoding
Date: Wed, 08 Mar 2017 21:59:23 GMT
Connection: keep-alive


{"status":401,"error":"invalid_token","error_description":"unknown_token"}

Similarly, if your token has been temporarily disabled due to suspicious activity, the API will also respond with an HTTP 401 response reporting an "invalid_token" error.  

403

If your request provides a valid token, but that token does not provide access to the function you are attempting to access, the API will respond with an HTTP 403 response.  The body of the response will contain an error of "insufficient_scope" and an error_description that provides additional information about why your token does not provide access to the requested function.  Your application should not retry the request.  Should your application receive a 403 error, you should check and verify that you are submitting the correct token and that you are accessing the intended API resource.  If you believe your token should have access to the resource and your application is receiving this response in error, please contact Third Iron Support at support@thirdiron.com so that we may work with you to resolve the issue.

Example:

HTTP/1.1 403 Forbidden
X-Powered-By: Express
Content-Type: application/json; charset=utf-8
Content-Length: 117
ETag: W/"75-2c6339fb"
Vary: Accept-Encoding
Date: Wed, 08 Mar 2017 22:02:24 GMT
Connection: keep-alive


{"status":403,"error":"insufficient_scope","error_description":"Your token is not authorized to access library 2000"}

Token Revocation

If you believe your API token has been compromised and someone may use it for unauthorized access to your organization's data, please contact Third Iron Support support@thirdiron.com so we may revoke the compromised token and issue your application a new one.

Rate Limiting

Our API imposes limits on its use.  Each registered client is allowed a certain number of requests during a specific interval of time. At the end of that period of time, the client's balance of requests is refreshed to the maximum allowed for the interval.

Standard Rate Limit Policy

Unless your application has a special agreement with Third Iron, it will be permitted to perform X requests within an interval of Y seconds.  If these limits don't meet your application's needs, please contact us at support@thirdiron.com and we can probably work something out.

Rate Limit Headers

Every API request should respond with headers to assist your application in understanding what limits are imposed upon it and what it needs to do to stay within limits.  Each response will include the headers described in the table below:

Rate Limit Exceeded Error

Should your application reach its limit, the API will respond with an HTTP 429 error.  The response will have a Retry-After header whose value is the number of seconds your application needs to wait before submitting more requests.  The body of the error response should hold a JSON error object with error property of "rate_limit_exceeded", an error_description property with more detail about the error, and a retry_after property that also holds the number of seconds your application needs to wait before submitting more requests.

Example:

HTTP/1.1 429 Too Many Requests
X-Powered-By: Express
X-RateLimit-Limit: 2
X-RateLimit-Remaining: -1
X-RateLimit-Reset: 1489013242
Retry-After: 52
Content-Type: application/json; charset=utf-8
Content-Length: 183
ETag: W/"b7-900d271c"
Vary: Accept-Encoding
Date: Wed, 08 Mar 2017 22:46:30 GMT
Connection: keep-alive


{"status":429,"error":"rate_limit_exceeded","error_description":"Your API client has exceeded the allowed limit for requests.  Please wait 52 seconds and try again.","retry_after":52}