API Documentation

Please read the sections below before trying to build any production software against the Pine API. While the API is designed to be simple and easy-to-use, there are a few powerful features and paradigms that you should be familiar with prior to starting development.

If you're ready to go, and you've read the sections below, then jump straight to the Endpoints Reference →

Note: The API is still under development and the format is subject to change, but we will try to maintain backwards compatibility in most cases. Fields may be added to responses, but rarely removed or changed unless absolutely necessary.


Table of Contents
  1. Throttling Limits
  2. Request Methods
  3. Response Codes
  4. Meta Entries
  5. Endpoints Reference →

Throttling Limits

General requests to the API and site are rate limited by client IP to ~60/minute to prevent spam. Normally this won't be an issue for users or for those looking to write simple scripts against the API. However if you need more frequent access to the API you can upgrade to a Premium Account to remove this restriction. Premium accounts are useful for anyone wanting to build production software against the Pine API.

Premium accounts can authenticate with the API to receive a time-limited access token and remove the ~60/minute limit. These premium accounts use an OAuth scheme called client_credentials and are designed to be invoked on a secure server which proxies requests to Pine from a client. Do not put your Premium API Keys in your web or native clients as neither can be trusted to keep the secret safe. If at any time you need to regenerate your API keys, you can do so from your account page.

Note: Requests to the API even with an access token are technically also rate limited to ~1000/minute to prevent spam. If you require that the limit be removed, please email support@skyrocket.software and we can talk about your needs.

Response Caching

As indicated, throttling limits are approximations and may in-fact be higher than indicated. This is because API results are cached for a short period to ease the burden of repeated, identical queries. This means that in practice the API limit you encounter could be slightly higher than but no less than the indicated limit if you repeatedly request the same data. You can see whether or not your query was served from the cache by checking the X-Proxy-Cache header.


Request Methods

The Pine API is a JSON-REST API and abides by most of the typical REST paradigms. The API uses response codes and HTTP request methods to determine intent. This is enforced as much as possible so while it may not be strictly the case for all endpoints, the vast majority of endpoints use the standard conventions.

Note: Endpoints with custom request method behavior will be noted as such in the endpoint's documentation.


Response Codes

Most response codes used by Pine's API reflect standard behaviour defined in the HTTP specification, however here are some common scenarios where you might encounter a response code and what it might mean.

Note: Endpoints with special response codes will be noted as such in the endpoint's documentation.


Meta Entries

API responses may, at any time, include a _meta entry at the top level. This entry will contain at least one important piece of information about the current query or endpoint. These can be deprecation notices, beta API notices, and more. These notices are intended to be read by a developer and provide helpful information about the requested API endpoint.

Deprecation Notices

Deprecation notices will often, but not always include an effective_date and replaced_by entry if one exists. In all cases the deprecation notice will have a plain-text message explaining the deprecation.

As an example, if an API was deprecated, then the developer requesting the deprecated API would see something like the following:

$ http http://pine.blog/api/some_deprecated_api

{
    "_meta": {
        "deprecation_notice": {
            "effective_date": "2018-01-01",
            "message": "Warning, this API has been deprecated and will be no longer be reliable after the specified date.",
            "replaced_by": "/api/some_new_api"
        }
    },
    // ...
}
Beta Notices

Endpoints are sometimes released while still in beta for developers to try out and give feedback. These APIs will not only be marked as beta in the documentation, but will also have a beta_notice in the meta section of all API responses.

Beta notices will often, but not always include an link entry which points to a section of the documentation explaining the new endpoint. In all cases the beta notice will have a plain-text message explaining that is is subject to change.

$ http http://pine.blog/api/some_beta_api

{
    "_meta": {
        "beta_notice": {
            "link": "https://pine.blog/api/documentation/endpoints#some_beta_api",
            "message": "Warning, this endpoint is currently in beta and is subject to change. Please see our documentation for more information."
        }
    },
    // ...
}