Prepr Documentation

Prepr Documentation

Welcome to the Prepr Documentation. You'll find comprehensive guides and documentation to help you start working with Prepr as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Overview and Best Practices

The API aims to be a RESTful resource

The Prepr API endpoints attempt to conform to the design principles of Representational State Transfer (REST). Our APIs use the JSON data format for responses (and in some cases, for requests).

The API is HTTP-based (over SSL)

Methods to retrieve data from the Prepr API require a GET request. Methods that submit, change, or destroy data require a POST, PUT or DELETE. API methods that require a particular HTTP method will return an (405) error if not invoked using the correct style. HTTP Response Codes are meaningful.

Dates and Times

By default in all API responses date are represented as an ISO8601 string. You can change this behaviour by sending a custom HTTP header called X-Graphlr-Response-Date-Format.

X-Graphlr-Response-Date-Format

Options:
- timestamp (unix timestamp)
- ISO8601 (2018-02-16T09:25:57+00:00)

Offset-based Pagination & Limits

Queries on the Prepr API can return large numbers of results. To improve performance and make the data more consumable, the API supports paginating large responses on most list endpoints.

An offset-paginated edge supports the following parameters:

parameter

skip

This offsets the start of each page by the number specified.

limit

This is the maximum number of objects that may be returned. A query may return fewer than the value of limit due to filtering. Do not depend on the number of results being fewer than the limit value to indicate your query reached the end of the list of data, use the absence of next instead as described below. Some endpoints may also have a maximum on the limit value for performance reasons. In all cases, the API returns the correct pagination links.

after

The API endpoint that will return the next page of data. If not included, this is the last page of data. Due to how pagination works with visibility and privacy, it is possible that a page may be empty but contain a 'next' paging link. Stop paging when the 'next' link no longer appears.

before

The API endpoint that will return the previous page of data. If null, this is the first page of data.

Note

That if new objects are added to the list of items being paged, the contents of each offset-based page will change.

Note

The maximum limit is 100 records per request unless documented otherwise.

Fields

Not all fields in a object are returned by default. You can choose the fields that you want returned with the parameter fields. This is really useful for making your API requests more efficient and fast.

Check out our guide How to use fields to get more information about how to use fields on the read endpoints.

Note

If fields is set as a request parameter and you send fields in postdata. Postdata will override the request parameter.

Read-After-Write

For create and update endpoints, the Prepr API can immediately read a successfully published or updated object and return any fields supported by the corresponding read endpoint.

To use this feature, include a fields parameter in your request and list the fields you want returned.

Audience actions

To do actions on a logged-in Person (like, bookmark, follow, comment, etc.) a session_hash is required in the request. The session hash is provided as an required parameter in the requests.

Rate limiting

API Rate limits specify the number of requests a client can make to Prepr APIs in a specific time frame. Every request counts against a per second and a per hour rate limit.

By default the Prepr API enforces rate limits of 50 requests per second and 20000 requests per hour. Higher rate limits may apply depending on your current plan.

HTTP Headers and Response Codes

Use the HTTP headers in order to understand where the application is at for a given rate limit, on the method that was just utilized.

*X-Prepr-RateLimit-Hour-Limit: the rate limit ceiling for the 60 minute window

*X-Prepr-RateLimit-Hour-Remaining: the number of requests left for the 60 minute window

*X-Prepr-RateLimit-Reset: the remaining window before the rate limit resets, in UTC epoch seconds