Overview

API v2 Introduction

The Prefinery API is implemented as JSON over HTTPS. Every resource, like Project or User has their own URL and are manipulated in isolation. We've tried to make the API follow the REST principles as much as possible.

Addressing

All API calls will be made over HTTPS at: https://api.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. 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 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 of the updated resource.

Finally, you can delete resources using the DELETE verb. The response to a successful delete is "200 OK".

Timestamps

All timestamps use UTC and are strings in the ISO 8601 combined date and time representation format: 2012-10-21T16:45:10Z

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.

Rate Limiting

If your API requests trigger our rate limiting, you will receive a HTTP Error 503: Service Unavailable error.

In addition to endpoint-specific rate limiting, there is limit of 256 simultaneous connections per IP address.

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.
400	Bad Request	The request could not be understood due to malformed syntax. Please modify your request and try again.
401	Unauthorized	Authentication credentials were missing or incorrect.
402	Payment Required	The account's plan does not have API access enabled.
403	Forbidden	The API key does not have permissions to perform this action.
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.
503	Service Unavailable	The rate limit has been reached.

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