API Overview

Introduction

The Prefinery API is implemented as XML over HTTP 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.

Addressing

All API calls will be made against the domain that your account is accessed from and the url will follow this template:

http://{yoursubdomain}.prefinery.com/api/v1/{resource}

For instance, if you want to get a list of all testers participating in beta 1 for the compulsivo account, you would access http://compulsivo.prefinery.com/api/v1/betas/1/testers.xml.

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.

If the read is successful, you'll get an XML response back along with the status code "200 OK".

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/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 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 XML of the updated resource.

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

Dealing with Errors

If you try to save an invalid resource, the API will return a set of validation methods, along with an HTTP status of 422 Unprocessable Entity. For example:

HTTP/1.1 422 Unprocessable Entity
<?xml version="1.0" encoding="UTF-8"?>
<errors>
  <error>Email has already been taken</error>
</errors>

Prefinery API Documentation

Topics