×

###MESSAGE###

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.

What's new and improved since the old v1 API?

  • JSON support in addition to XML
  • Ability to answer Application Form questions
  • Ability to read & write feedback (i.e. API access to the Feedback Widget)
  • Ability to send Friend Invitations (i.e. API access to the Invite-a-Friend Widget)
  • Improved pagination information
  • Improved errors — complete with unique error codes

Addressing

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:

https://{yoursubdomain}.prefinery.com/api/v2/{resource}

Reading

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.

Writing

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".

Pagination

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:

X-Pagination: {"previous_page":null,"next_page":2,"current_page":1,"per_page":25,"count":25,"pages":2,"total_count":30}

Possible X-Pagination values are:

previous_page The previous page. null if there is no previous page.
next_page The next page. null if there is no next page.
current_page The current page.
per_page The maximum number of records returned per page.
count The number of records returned on this page.
pages The total number of pages.
total_count The total number of records across all pages.

Error Codes & Responses

HTTP Status Codes

The Prefinery API attempts to return appropriate HTTP status codes for every request.

HTTP Code Text Description
200 OK Success!
201 Created Object was successfully created.
202 Accepted Your request was queued (in the background) for processing.
401 Unauthorized Authentication credentials were missing or incorrect.
404 Not Found The URI requested is invalid or the resource requested, such as a tester, does not exists.
422 Unprocessable Entity Returned when fields are either absent or invalid.
500 Internal Server Error Something is broken. Check your request and contact support if you are unable to resolve the issue.

Error Messages

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:

{
  "errors": [
    {
      "code": 2302,
      "message": "Email is required."
    }
  ]
}

The corresponding XML response would be:

<?xml version="1.0" encoding="UTF-8"?>
<errors type="array">
  <error>
    <code type="integer">2302</code>
    <message>Email is required.</message>
  </error>
</errors>