API v1

This describes the resources that make up the official TAP API v1. If you have any problems or requests please contact support.

Schema

All API access is over HTTPS, and accessed from the tapability.org/api/v1 domain. All data is sent and received as JSON.

$ curl -i https://tapability.org/api/v1/jobs

HTTP/1.1 200 OK
Server: nginx
Content-Type: application/json;charset=utf-8
Date: Wed, 06 Nov 2013 16:18:21 GMT
Connection: keep-alive
Status: 200 OK
Strict-Transport-Security: max-age=31536000
ETag: "a00049ba79152d03380c34652f2cb612"
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999
Content-Length: 5
Cache-Control: max-age=0, private, must-revalidate
X-Content-Type-Options: nosniff
X-Powered-By: Phusion Passenger
X-Request-Id: f5c3278a-9f6f-42e4-a9cd-607a24e3b2c6
X-Runtime: 0.004713

[]

Blank fields are included as null instead of being omitted.

All timestamps are returned in ISO 8601 format:

YYYY-MM-DDTHH:MM:SSZ

Parameters

Many API methods take optional parameters. For GET requests, any parameters not specified as a segment in the path can be passed as an HTTP query string parameter:

$ curl -i "https://tapability.org/api/v1/jobs?sort=created"

In this example, the :sort parameter is passed in the query string.

For POST requests, parameters not included in the URL should be encoded as JSON with a Content-Type of ‘application/x-www-form-urlencoded’:

$ curl -H "X-TAP-Token: TOKEN" -d '{"title":"Assistant Regional Manager","description":""}' https://tapability.org/api/v1/jobs

Client Errors

There are three possible types of client errors on API calls that receive request bodies:

  1. Sending invalid JSON will result in a 400 Bad Request response.

     HTTP/1.1 400 Bad Request
 Content-Length: 35

 {"message":"Problems parsing JSON"}

  2. Sending the wrong type of JSON values will result in a 400 Bad Request response.

     HTTP/1.1 400 Bad Request
 Content-Length: 40

 {"message":"Body should be a JSON Hash"}

  3. Sending invalid fields will result in a 422 Unprocessable Entity response.

     HTTP/1.1 422 Unprocessable Entity
 Content-Length: 149

 {
   "message": "Validation Failed",
   "errors": [
     {
       "resource": "Job",
       "field": "date",
       "code": "missing_field"
     }
   ]
 }

All error objects have resource and field properties so that your client can tell what the problem is. There’s also an error code to let you know what is wrong with the field. These are the possible validation error codes:

missing
This means a resource does not exist.
missing_field
This means a required field on a resource has not been set.
invalid
This means the formatting of a field is invalid. The documentation for that resource should be able to give you more specific information.
already_exists
This means another resource has the same value as this field. This can happen in resources that must have some unique key (such as Label names).

If resources have custom validation errors, they will be documented with the resource.

HTTP Redirects

API v1 uses HTTP redirection where appropriate. Clients should assume that any request may result in a redirection. Receiving an HTTP redirection is not an error and clients should follow that redirect. Redirect responses will have a Location header field which contains the URI of the resource to which the client should repeat the requests.

301
Permanent redirection. The URI you used to make the request has be superseded by the one specified in the Location header field. This and all future requests to this resource should be directed the new URI.
302, 307
Temporary redirection. The request should be repeated verbatim to the URI specified in the Location header field but clients should continue to use the original URI for future requests.

Other redirection status codes may be used in accordance with the HTTP 1.1 spec.

HTTP Verbs

Where possible, API v1 strives to use appropriate HTTP verbs for each action.

HEAD
Can be issued against any resource to get just the HTTP header info.
GET
Used for retrieving resources.
POST
Used for creating resources, or performing custom actions (such as expiring a job listing).
PATCH
Used for updating resources with partial JSON data. For instance, a job resource has title and description attributes, among others. A PATCH request may accept one or more of the attributes to update the resource.
DELETE
Used for deleting resources.

Authentication

ALL API requests require authentication. There are no exceptions.

Requests to valid endpoints will return 404, instead of 403, in some places. This is to prevent the accidental leakage of private information to unauthorized users.

General API usage uses keys (tokens) for authentication. A single account can have any number of keys, allowing users to invalidate a token used on with a particular service or device. All user keys are immediately revoked when a user changes their password.

Initial API requests authenticate with the email address and password for the account to receive a token using a POST request to the keys endpoint. See the User Keys documentation for details.

$ curl -u "dwight@tapability.org" https://tapability.org/api/v1/me/keys

Token (sent in a header)

$ curl -H "X-TAP-Token: TOKEN" https://tapability.org/api/v1/me

Pagination

Requests that return multiple items will be paginated to 30 items by default. You can specify further pages with the ?page parameter. For some resources, you can also set a custom page size up to 200 with the ?per_page parameter.

$ curl https://tapability.org/api/v1/jobs?page=2&per_page=200

The pagination info is included in the Link header. It is important to follow these Link header values instead of constructing your own URLs.

Linebreak is included for readability.

The possible rel values are:

next
Shows the URL of the immediate next page of results.
last
Shows the URL of the last page of results.
first
Shows the URL of the first page of results.
prev
Shows the URL of the immediate previous page of results.

Rate Limiting

We limit API requests to 2,000 per hour. You can check the returned HTTP headers of any API request to see your current status:

$ curl -i https://tapability.org/api/v1/me

HTTP/1.1 200 OK
Status: 200 OK
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999

Requests that repeatedly fail authentication have a low, undisclosed rate limit to prevent abuse and brute force attacks.

User Agent Required

All API requests are encouraged to send a valid User Agent string. This is usually the HTTP client that you are using. This is so we can contact you if there are problems.

Conditional requests

Most responses return Last-Modified and Etag headers. You can use the values of these headers to make subsequent requests to those resources using the If-Modified-Since and If-None-Match headers, respectively. If the resource has not changed, the server will return a 304 Not Modified. Also note: making a conditional request and receiving a 304 response does not count against your Rate Limit, so we encourage you to use it whenever possible.

$ curl -i https://tapability.org/api/v1/me
HTTP/1.1 200 OK
Cache-Control: private, max-age=60
ETag: "644b5b0155e6404a9cc4bd9d8b1ae730"
Last-Modified: Thu, 05 Jul 2012 15:31:30 GMT
Status: 200 OK
Vary: Accept, Authorization, Cookie
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999

$ curl -i https://tapability.org/api/v1/me -H "If-Modified-Since: Thu, 05 Jul 2012 15:31:30 GMT"
HTTP/1.1 304 Not Modified
Cache-Control: private, max-age=60
Last-Modified: Thu, 05 Jul 2012 15:31:30 GMT
Status: 304 Not Modified
Vary: Accept, Authorization, Cookie
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999

$ curl -i https://tapability.org/api/v1/me -H 'If-None-Match: "644b5b0155e6404a9cc4bd9d8b1ae730"'
HTTP/1.1 304 Not Modified
Cache-Control: private, max-age=60
ETag: "644b5b0155e6404a9cc4bd9d8b1ae730"
Last-Modified: Thu, 05 Jul 2012 15:31:30 GMT
Status: 304 Not Modified
Vary: Accept, Authorization, Cookie
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999