API v2 Introduction
The Prefinery API is implemented as JSON (the default) and XML over HTTPS using all four verbs (GET/POST/PUT/DELETE). Every resource, like Beta or Tester has their own URL and are manipulated in isolation. We've tried to make the API follow the REST principles as much as possible.
All API calls will be made over HTTPS and against the domain that your account is accessed from and the url will follow this template:
The Prefinery API has two categories of actions for reading: Show and Index. Show returns a single record and index returns a collection. Both of these actions are done through GET and can be easily examined through your Web browser. Curl is also a great utility for exploring the API.
Creating, updating, and deleting resources through the API is almost as easy as reading, but you can't explore it as easily through a Web browser. Curl is a great utility and will become your best friend.
All create and update requests must send a proper Content-Type header of 'application/json' or 'application/xml'. Otherwise, Prefinery won't interpret your request correctly and you'll likely get a 500 error back.
Creating resources is done through the POST verb. The response to a successful creation is the status code "201 Created" along with the complete JSON or XML for the created resource.
Updating resources is done through the PUT verb and against the URL of the resource you want to update. The response to a successful update is "200 OK" along with the complete JSON or XML of the updated resource.
Finally, you can delete resources using the DELETE verb. The response to a successful delete is "200 OK".
Requests that return multiple items will be paginated. You can specify further pages with the ?page parameter. Pagination information will be returned in the X-Pagination header, for example:
Possible X-Pagination values are:
||The previous page. null if there is no previous page.
||The next page. null if there is no next page.
||The current page.
||The maximum number of records returned per page.
||The number of records returned on this page.
||The total number of pages.
||The total number of records across all pages.
There is limit of 256 simultaneous connections per IP address. If this limit is reached you will receive a HTTP Error 503: Service Unavailable.
HTTP Status Codes
The Prefinery API attempts to return appropriate HTTP status codes for every request.
||Object was successfully created.
||Your request was queued (in the background) for processing.
||The request could not be understood due to malformed syntax. Please modify your request and try again.
||Authentication credentials were missing or incorrect.
||The account's plan does not have API access enabled.
||The URI requested is invalid or the resource requested, such as a tester, does not exists.
||Returned when fields are either absent or invalid.
||Internal Server Error
||Something is broken. Check your request and contact support if you are unable to resolve the issue.
||The rate limit has been reached.
When the Prefinery API returns error messages, it does so in your requested format. We will set the HTTP Status Code to one of the above and return to you a list of errors. Where possible, we will try to return both a unique error code (this is not the same as the HTTP Status Codes list above) and a helpful message. While a code won't always be included, a message will.
An error from a JSON method might look like this:
"message": "Email is required."
The corresponding XML response would be:
<?xml version="1.0" encoding="UTF-8"?>
<message>Email is required.</message>