photoSentinel API Additional Usage Documentation

Metrics will be tracked against calls, limits are placed on the number of calls to provide protection for the photoSentinel infrastructure.

When a new version of a function becomes available and the older version is deprecated, a header will be added to the response to that call that provides the support end time. That support end time is expected to be 6 months. After that time, the function will cease operating at any point without notice.

X-Supported-Until: yyyy-MM-ddTHH:mm:ssZ

The return JSON of an API function may be altered to add new data elements without increasing the version. Any changes to the definition of existing data elements or the removal of those elements will result in version increase for that call.

An api_key needs to be generated on the photoSentinel Web App for the user to use the API. The api_key must be stored securely as this is as important as the user’s username and password.

The api_key must be sent as part of the request header with all client requests and must use the “Authorization” header. The api_key is used to authenticate the request and identify the user of the request.

Sample Request Header

Content-Type: application/json
Accept: application/json
Authorization: apiKey {api_key}

Authenticating On The API Documentation Page

1. Click on one of the endpoints.
2. Click on the red icon .
3. Enter your api_key using the following format "apiKey {api_key}" on the input box.
4. Click Authorize.
5. You are now ready to test out the endpoints.

To protect the photoSentinel infrastructure, we have implemented rate limits. We believe that these rate limits are enough for general use.

There are two types of rate limits.

• Per minute rate limit
• Monthly rate limit

Reaching either of the rate limits will return a rate limit response with a response header "Retry-After" date time string of when you can next make a successful call.

Sample Rate Limit Response

Status Code: 429
Retry-After: Tue, 01 Jun 2021 00:00:00 GMT

{
    "ok":false,
    "error": {
      "code":"rate_limit",
      "message":"API rate limit exceeded. Please try again after Tue, 01 Jun 2021 00:00:00 GMT."
    }
}

Photo URLs found on but not limited to the following json keys requires authentication to access:

• thumb_url
• preview_url
• original_url
• watermark_url

Also, these urls are redirect urls and will have to be used with that in mind.

Sample code to use these urls for downloading to a file. Where anything inside [] needs to be replaced by actual values:

curl -L '[preview_url]' -H 'Authorization: apiKey [user's api key here]' -o [output file name here]