API Basics

Company based API

The API is published and limited by the Interview Suite hostname for such company. That means it’s not possible to get access to a company’s data using another company’s API. That turns security process transparent and strong to rely on.

RESTful

The interview suite API version 3 follows RESTful architecture, which means HTTP methods and status codes are used as a main reference to determine request and response types.

It can be read with more details in publicly available contents, such as in Wikipedia:

• http://en.wikipedia.org/wiki/Representational_state_transfer

HTTP Methods

For listing resources

Listing resources are usually the root resource URL, with no ID bit informed, for example:

• https://interview-suite.com/api/v3/companies/1/projects/

GET	Requests a list of objects of such resource, possibly include a query string for filtering or pagination reasons (each resource has their own available filters).
POST	When allowed, the POST method creates a new resource object, which must include all required fields as described for each resource.

For object resources

Object resources are usually the root resource URL appended by the ID bit, for example:

• https://interview-suite.com/api/v3/companies/1/projects/123/

GET	Requests all available details of an object with such informed ID.
PATCH	Updates an object. All fields are optional, when only informed fields are really validated and updated in such object. In case some field value is incompatible with current state or another field value, validation error is presented.
DELETE	Deletes such object from the database with no possible recovery.

HTTP Status Codes

More details can be found in publicly available content, such as:

• http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html

The main status codes used by our API are:

200	Successful response
201	New resource object was created successfully
202	Object update was accepted successfully
400	Bad request. The informed attributes are invalid or contain invalid value
401	Unauthorized. User is not authenticated or authenticated user has no access to such resource.
403	Forbidden. Returned when a valid user with a valid token got no access to a certain resource.
404	Resource not found
500	Server error. Despite our engineers work hard to never return this response to API consumers, it’s always technically possible to return such status code in case of an internal server error.

JSON format

Responses always return valid standard JSON content, which is simple and supported by any standard language in the market.

For POST and PATCH requests it’s expected a payload (request body) with attributes in JSON format too.

Example:

curl -i -X POST \
  -H 'Content-Type: application/json' \
  -d '{"username":"tarsila@viasto.com"}' \
  https://interview-suite.com/api/v3/api-token-auth/

HTTP/1.1 400 BAD REQUEST
Date: Thu, 07 May 2015 08:12:38 GMT
Server: Apache
Vary: Accept-Language,Cookie
Content-Language: en-us
Allow: POST, OPTIONS
Content-Length: 41
Connection: close
Content-Type: application/json

{"password": ["This field is required."]}

Nested URLs

To turn easier implementation and validation in client side and also allow flexibility for future improvements, our API follows the standard of nested URLs, which means that certain resources are always requested in context of another container resource.

That is all about how the URLs are built and follow strict and simple standards.

The best example for such is that all projects in a company must be requested as part of such company:

A company:

https://interview-suite.com/api/v3/companies/1/

All projects in such company:

https://interview-suite.com/api/v3/companies/1/projects/

A specific project with ID 15:

https://interview-suite.com/api/v3/companies/1/projects/15/

Full URI IDs

To ensure a full trackable and flexible object identification, resource objects always return their IDs in full URI format, for example:

https://interview-suite.com/api/v3/companies/1/projects/17/

That turns easy for integrating systems to store the full URL and rely that will be always unique and fully accessible as a valid resource. It’s also possible to inform the equivalent shorter term, for example:

/companies/1/projects/17/

Incoming Links describes the relationship between an APIv3 resource and the user-facing interface in the interview suite. This can be used to render a link that leads users to an appropriate page in the interview suite.

Root endpoint

As a starting point, it’s recommended the API clients to always call the root end point as initialization procedure, in order to get the basic API end points, for example:

curl \
  -H 'Authorization: Token a9e75326e273e8ef865522ac326b457ef1864e9e'
  https://interview-suite.com/api/v3/

{"whoami_uri": "https://interview-suite.com/api/v3/whoami/",
 "contenttemplates_uri": "https://interview-suite.com/api/v3/contenttemplates/",
 "auth_token_auth_uri": "https://interview-suite.com/api/v3/api-token-auth/",
 "company_uri": "https://interview-suite.com/api/v3/companies/1/",
 "design_uri": "https://interview-suite.com/api/v3/companies/1/design/",
 "settings_uri": "https://interview-suite.com/api/v3/companies/1/settings/",
 "projects_uri": "https://interview-suite.com/api/v3/companies/1/projects/",
 "customers_uri": "https://interview-suite.com/api/v3/companies/1/customers/",
 "videos_uri": "https://interview-suite.com/api/v3/companies/1/videos/"}

Loading related objects

In some cases loading a complex resource can require multiple API calls. To reduce the amount of time spent on network round trips, some objects support nested objects inclusion. For example, appending ?include_nested=questions,criteria when requesting a project record will return the question and criteria objects nested inside the parent project, instead of just resource_uris pointing to the resource. Nested records are available on the following resources:

• Project resource

HTTPS

API calls must always be done to the HTTPS URL (HTTP is invalid), which means all transactions follow strict security concerns. Certificate validation is highly recommended for the client implementation, despite it could be used for testing purposes.

Basic list resources

All list resources requests support the following parameters:

page	default is 1. The page number to objects list
page_size	default is 10. Determines the size of a page, so, if this is set to 100 and page is set to 1, the first 100 objects are returned. If page is 2, then, objects from position 101 to 200 are returned, and so on.

All list resources output responses in the following standard:

{"meta":{
    "total_count":135,
    "previous":"https://interview-suite.com/api/v3/companies/1/customers/?page=1&page_size=50",
    "next":"https://interview-suite.com/api/v3/companies/1/customers/?page=3&page_size=50"
 },
 "objects":[]
 }

meta	meta information about
meta.total_count	the total amount of objects available for querying (not only the ones limited by current page)
meta.previous	URL pointing to previous page respecting params page and page_size
meta.next	URL pointing to next page respecting params page and page_size
objects	list of objects in the same format as when returned object details