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).
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.
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 Options: - timestamp (unix timestamp) - ISO8601 (2018-02-16T09:25:57+00:00)
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:
This offsets the start of each page by the number specified.
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.
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.
The API endpoint that will return the previous page of data. If null, this is the first page of data.
That if new objects are added to the list of items being paged, the contents of each offset-based page will change.
The maximum limit is 100 records per request unless documented otherwise.
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.
If fields is set as a request parameter and you send fields in postdata. Postdata will override the request parameter.
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.
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.
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.
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