API Client Implementation Guide

  • Before any calls can succeed, an OAuth client id and secret pair issued by PowerReviews is required. Viewing existing client ids and creating new credential pairs is available in the self service portal at https://portal.powerreviews.com/enterprise_credentials - displaying existing secrets in this UI is not available. You can use this UI to rotate to new credentials in the future, if desired. Client secrets should not be shared in plaintext publicly.

  • First, using the credential pair as Authorization Basic (base64 encoded “client_id:client_secret”) and Content-Type: application/x-www-form-urlencoded make an HTTP POST request to the authorization endpoint https://enterprise-api.powerreviews.com/oauth2/token?grant_type=client_credentials

    • The OAuth2 token returned in a successful response expires in 1 hour. We have the ability to change this expiration time to be a value between 5 minutes and 24 hours, inclusive, for your account, if requested.
    • Follow the same process to get a new token after the initial one expires.
    • To avoid receiving 401 Unauthorized responses due to using a token that expires during the request call, it is recommended to refresh the token some time before the expiration (ex. 1 minute).
  • Next, make HTTP GET/PUT/POST etc. calls using the OAuth2 token as the value of the Authorization header. The available EAPI data endpoints are listed at https://apidocs.powerreviews.com/ - note that some API endpoints do not have paginated responses. There are endpoints for retrieving individual pieces of content instead of a page of content, which may be useful for retries and troubleshooting individual content items.

  • Encoding - Set the Accept-Encoding request header and look for the Content-Encoding response header. Not sending Accept-Encoding does not guarantee the response will not be encoded, if the response is above 10MB uncompressed. Compressing and decompressing the response uses additional CPU on the server and client, but the network size of the response will be much smaller in most cases, resulting in greater overall performance per request. If Accept-Encoding is set to gzip, any size response will be compressed with that method.

  • Content Type - Accept and Content-Type headers are expected to be application/json - We do not support XML or other serialization formats at this time. Expect all responses, including error responses, from the API to be in json format.

  • Character encoding - All character encoding should be UTF-8 in the request and response.

  • Pagination - Make requests in sequence by setting the next_page response value from the current response as the next_page query parameter value in the next request. If no next_page id is provided in a response, that is the indicator that the current response is the final page of results. Alternatively, use the fully formed next_page_request_path response value to make a new HTTP request.

  • Filters - Please refer to the documentation for the specific endpoint you are calling for the details on the available filters and how each affects the response. Most filters can be combined.

  • HTTP codes of note:

    • 200 OK - The server responded with the requested data with no complications
    • 202 Accepted - The server Accepted new data for processing in an asynchronous process
    • 4xx Error Codes - There was a problem with the client request. We expect the client to identify and resolve this problem before making more requests. Do not attempt to retry with an identical request, except if the code is 429.
    • 401 Unauthorized - The OAuth2 token has likely expired. If this persists after retrieving and using a new token, then contact support.
    • 429 Too Many Requests - We do not currently send this response, but we may in the future. It should be treated by the client as a retry of an identical request with an exponential backoff.
    • 500 Internal Server Error - A catch-all for something going wrong on the server side. Retries may or may not produce a better result, but should be spaced apart by 60s or set a unique query parameter to avoid cached responses. If the issue persists, contact support.
    • 502 Bad Gateway - The service is down and may not be available soon. Retry with an exponential backoff. If the issue persists with this or a 503 Service Unavailable, contact our support.
    • 503 Service Unavailable - The service is temporarily unavailable due to a network configuration change or server restart. Retry several times with a backoff.
    • 504 Gateway Timeout - The server is taking too long to respond and our network gateway timeout has taken effect, terminating the request. The timeout is 30 seconds. If this response is received, immediately retry with an exponential backoff period between further retries. Clients can retry an indefinite number of times. Adjusting the limit parameter can also alleviate these issues as it reduces the load on the system and decreases the likelihood that a timeout will occur.
  • Caching - We cache responses in our CDN layer using request URLs as keys. The following are the response codes that are cached and their minimum time-to-live:

    • All 2xx, 3xx - 0 seconds
    • 400 Bad Request - 10 seconds
    • 403 Forbidden - 10 seconds
    • 404 Not Found - 3600 seconds (1 hour)
    • Other 4xx - 0-10 seconds
    • 500 Internal Server Error - 60 seconds
    • 502 Bad Gateway - 0 seconds
    • 503 Service Unavailable - 0 seconds
    • 504 Gateway Timeout - 0 seconds
    • Other 5xx - 0-10 seconds
    • To ignore a cached response on a subsequent request, change the url in some fashion. A safe way to do this is to add a dummy query parameter with a random value, e.x. &_nocache=
  • The server implements cursor paging (A decent overview and contrast between that and offset paging can be found here: https://slack.engineering/evolving-api-pagination-at-slack/)

  • Concurrent paging requests of the same content type are not advised. For example, one thread paging through the reviews API and one thread paging through the questions API is fine, and we do not advise having two or more threads paging through the reviews API, since it is not possible to predict the cursor id for the next page in the current implementation.

  • The API request limit per client is 10 TPS for data endpoints.