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:
Submit the token as part of an Authorization header as shown:
Authorization: Bearer ffffffff-ffff-ffff-ffff-ffffffffffff
Submit the token as the access_token querystring parameter as shown:
GET https://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:
Header | Type | Description |
---|---|---|
X-RateLimit-Limit | number | Specifies how many requests your application is allowed to make during each reset interval according to the policy applicable to your application |
X-RateLimit-Remaining | number | The number of requests remaining for the current refresh interval. Should this reach zero, the API will begin to emit HTTP 429 Error Responses |
X-RateLimit-Reset | number | The time at which your application's remaining requests will reset to the limit, represented in Unix epoch time |
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}
Entitlements Data Endpoints
BrowZine Search Endpoint
The BrowZine Search Endpoint allows your application to integrate with the search functionality that powers the search on browzine.com. Submit a GET request against this endpoint with a search query and your application will get a response representing the results that would be presented to a user if they were to perform that same search query within the journal/subject search of browzine.com. Responses contain an array of result objects of two types: journal results and subject area results. The array returned in the response is ordered according to relevance to the submitted search query using the same rules as the browzine.com search.
BrowZine Search Request:
Supported Methods | GET |
---|---|
Endpoint Location | /public/v1/libraries/:library_id/search |
Endpoint Parameters | |
:library_id | Replace the :library_id portion of the endpoint path with the id # of your library |
?query | Supply a querystring parameter of ?query=[searchQuery] where [searchQuery] is a urlencoded representation of the search you wish to perform against your library's journals and subject areas |
BrowZine Search Response:
The browzine search endpoint responds with a JSON object holding an array of result objects. This array is ordered by relevance to the search query. Like the search in browzine.com, there are two kinds of search results: journal results and subject results. Each journal result represents a publication that the library has some entitlement to, and each subject area result represents a taxonomic category in the browzine system that your library's collection has content within. The structure of the response overall and individual journal and subject results are described in the following tables and an example of search for "Bio" may also be found below.
Response Object:
Property | Type | Description |
---|---|---|
data | Array of Object | An Array of Journal Result objects and Subject Result objects, sorted by relevance to the query, may hold up to 250 results |
Journal Result:
Each journal result represents a journal that the queried library's collection has access to in some form that is revelent to the searched for query. Results include both titles that are BrowZine enabled and thus enjoy full TOC browsing support, the ability to add these titles to My Bookshelf and so on as well as Externally Linked titles that Browzine does not natively support, but that are found within the library's collection. Whether a title is supported by the browzine.com application is captured by the browzineEnabled property of the result object. Results for journals that are browzineEnabled at the queried library will have a browzineWebLink that links to the journal within browzine.com, and results for journals that are not browzineEnabled will have an externalLink property that links to the journal in the queried library's A-Z system if the queried library has been configured to integrate with the library's A-Z system. Each browzineEnabled journal result also provides a coverImageUrl that can be used to visually depict the journal within your application.
The full list of properties that may appear on a journal result are described in detail in the table below:
Property | Type | Description | Optional |
---|---|---|---|
id | number | The journal's unique id in the Browzine system | No |
type | string | For a journal result, the type will have value "journals" | No |
title | string | The journal's title | No |
issn | string | An issn for the journal (formatted with no hyphen) | No |
browzineEnabled | boolean | True when the title is available within Browzine at the specified library | No |
coverImageUrl | string | A url to a small image that can be used to visually depict the journal | No |
sjrValue | number | The Scimago Journal Rank (SJR) - see all their ranking at their website | No |
browzineWebLink | string | On titles that are browzine enabled, this property will be present and will link to the journal within browzine.com | Yes |
externalLink | string | On titles that are not browzine enabled, this property may be present and when it is will link to the journal within the library's A-Z system | Yes |
Subject Result:
Each subject result represents a taxonomic category that the queried library's collection contains some publication within the category and whose name is relevant to the searched for query. Results include the name of the subject area and a link to the subject area in browzine.com.
Property | Type | Description | Optional |
---|---|---|---|
id | number | The subject's unique id in the Browzine system | No |
type | string | For a subject result, the type will have value "subjects" | No |
name | string | The name of the subject area | No |
browzineWebLink | string | A link to the subject area within Browzine Web | No |
Example Request:
GET /public/v1/libraries/:library_id/search?query=Bio
Example Response:
{ "data": [ { "id": 2911, "type": "journals", "title": "Biocatalysis and Agricultural Biotechnology", "issn": "18788181", "browzineEnabled": true, "coverImageUrl": "https://assets.thirdiron.com/images/covers/1878-8181.png", "sjrValue": 0 }, { "id": 771, "type": "subjects", "name": "Biochemical and Biomolecular Engineering", "browzineWebLink": "https://browzine.com/libraries/13/subjects/75/bookcases/146" }, { "id": 5006, "type": "journals", "title": "Biochemical Pharmacology", "issn": "00062952", "browzineEnabled": true, "coverImageUrl": "https://assets.thirdiron.com/images/covers/0006-2952.png", "sjrValue": 0 }, { "id": 5016, "type": "journals", "title": "Biochemical Systematics and Ecology", "issn": "03051978", "browzineEnabled": true, "coverImageUrl": "https://assets.thirdiron.com/images/covers/0305-1978.png", "sjrValue": 0 }, ... ] }
BrowZine Journal Availability Endpoint
The BrowZine Journal Availability Endpoint allows your application to determine whether a journal is available at browzine.com, and provides some basic information to help link to the journal within BrowZine at your library.
Submit a GET request against this endpoint with a search query and your application will get a response representing the results that would be presented to a user if they were to perform that same search query within the journal/subject search of browzine.com. Responses contain an array of result objects of two types: journal results and subject area results. The array returned in the response is ordered according to relevance to the submitted search query using the same rules as the browzine.com search.
BrowZine Journal Availability Request:
Supported Methods | GET |
---|---|
Endpoint Location | /public/v1/libraries/:library_id/search |
Endpoint Parameters | |
:library_id | Replace the :library_id portion of the endpoint path with the id # of your library |
?issns | Supply a querystring parameter of ?issns=issn_list where issn_list is a comma-delimited list of ISSNs (up to 50) without the dash |
BrowZine Journal Availability Response:
The browzine journal availability endpoint responds with a JSON object holding an array of journal result objects. This array is not necessarily in the same order as the order of ISSNs passed in. Each journal result represents a publication that the library has some entitlement to. The structure of the response overall and individual journal results are described in the following tables.
Response Object:
Property | Type | Description |
---|---|---|
data | Array of Object | An Array of Journal Availability objects, sorted by relevance to the query, may hold up to 50 results |
Journal Result:
Each journal result represents a journal that the queried library's collection has access to in some form that has an ISSN (or eISSN) passed in. Results include both titles that are BrowZine enabled (which allow full Table of Contents browsing), and titles external to Browzine, but within a library's purchased materials.
Whether a title is supported by the browzine.com application is captured by the browzineEnabled property of the result object. Results for journals that are browzineEnabled at the queried library will have a browzineWebLink that links to the journal within browzine.com, and results for journals that are not browzineEnabled will have an externalLink property that links to the journal in the queried library's A-Z system if the queried library has been configured to integrate with the library's A-Z system. Each browzineEnabled journal result also provides a coverImageUrl that can be used to visually depict the journal within your application.
The full list of properties that may appear on a journal result are described in detail in the table below:
Property | Type | Description | Optional |
---|---|---|---|
id | number | The journal's unique id in the Browzine system | No |
type | string | has the value "journals" | No |
title | string | The journal's title | No |
issn | string | The issn for the journal that matches the issn passed in on the endpoint (formatted with no hyphen) | No |
browzineEnabled | boolean | True when the title is available within Browzine at the specified library | No |
coverImageUrl | string | A url to a small image that can be used to visually depict the journal | No |
sjrValue | number | The Scimago Journal Rank (SJR) - see all their ranking at their website | No |
browzineWebLink | URL | On titles that are browzine enabled, this property will be present and will link to the journal's current issue within browzine.com | Yes |
externalLink | URL | On titles that are not browzine enabled, this property may be present. When it is, it is a link to the journal within the library's A-Z system | Yes |
Example Request:
GET /public/v1/libraries/:library_id/search?issns=00280836,3940182X
Example Response:
{ "data": [ { "id": 13191, "type": "journals", "title": "Nature", "issn": "00280836", "sjrValue": 21.936, "coverImageUrl": "https://assets.thirdiron.com/images/covers/0028-0836.png", "browzineEnabled": true, "browzineWebLink": "http://browzine.com/libraries/222/journals/13191" }, { "id": 52627, "type": "journals", "title": "Consumer Reports", "issn": "00107174", "sjrValue": 0, "coverImageUrl": "https://assets.thirdiron.com/images/covers/00107174.png", "browzineEnabled": false, "externalLink": "http://knownitem.search.edu/?jtitle=Consumer%3Reports&jissn=3940-182X" } ] }
BrowZine Article DOI Lookup Endpoint
The BrowZine Article DOI Lookup Endpoint allows your application to determine whether an article is available at browzine.com, and provides some basic information to help link to the article within the context of the issue in BrowZine at your library.
Submit a GET request against this endpoint with a DOI and your application will get a response indicating if that article can be found in the designated library within BrowZine. If the DOI matches the DOI of an article in the BrowZine system, the response will contain an "Article Result" JSON object with metadata about the article reference by the specified DOI.
BrowZine Journal Availability Request:
Supported Methods | GET |
---|---|
Endpoint Location | /public/v1/libraries/:library_id/articles/doi/:article_doi |
Endpoint Parameters | |
:library_id | Replace the :library_id portion of the endpoint path with the id # of your library |
:article_doi | Replace :article_doi with the DOI of an article. Only one DOI can be supplied. (DOI value does not need to be URI encoded) |
BrowZine Article DOI Lookup Response:
The BrowZine Article DOI Lookup endpoint responds with a JSON object if the article is found in the BrowZine system at all. If it is found, this indicates that BrowZine recognizes this article DOI. The accompanying metadata then will indicate if it is "availableThroughBrowZine" for the given library. If it is, additional metadata about the article, including the browzineWebLink is provided. The structure of the response overall is described in the following tables.
Response Object:
Property | Type | Description |
---|---|---|
data | Object | An Article Result object is returned if the DOI is recognized by the BrowZine Article DOI Lookup Endpoint |
Article Result:
An article result represents an article that the BrowZine system is aware of. Responses from the "DOI lookup" endpoint then describe articles that have DOI's that BrowZine is aware of but are not in the specified BrowZine Library (:library_id) as well as articles that are within that library. A response indicates whether the article referenced by a DOI is available at the specified library by setting the article result's "availableThroughBrowZine" property to true when the article is available at the library, and false when it is not.
The full list of properties that may appear on a journal result are described in detail in the table below:
Property | Type | Description | Optional |
---|---|---|---|
id | number | The journal's unique id in the Browzine system | No |
type | string | has the value "articles" | No |
title | string | The article's title | Yes |
date | string | The date of the article | No |
authors | string | The authors of the article | Yes |
inPress | boolean | True when the article is not yet assigned to a regularly published issue and is considered an "Article in Press". False when it is in a regularly published issue | No |
availableThroughBrowZine | boolean | True when the article is available within Browzine at the specified library | No |
startPage | string | The page the article starts on | Yes |
endPage | string | The page the article ends on | Yes |
browzineWebLink | URL | On titles that are browzine enabled, this property will be present and will link to the article in the context of its issue (or articles in press list as appropriate) on browzine.com | No |
Example Request:
GET /public/v1/libraries/:library_id/articles/doi/10.1056/NEJMe1702728
Example Response:
{ "data": { "id": 76582654, "type": "articles", "title": "Assessment of Stable Coronary Lesions", "date": "2017-05-11", "authors": "Bhatt, Deepak L.", "inPress": false, "availableThroughBrowzine": true, "startPage": "1879", "endPage": "1881", "browzineWebLink": "https://browzine.com/libraries/222/journals/10292/issues/36167007?showArticleInContext=doi:10.1056/NEJMe1702728" } }