API Basics

In this chapter you’ll find HTTP API common bits about design and workflow.

HTTP Basics

TicketsCloud API is based on HTTP, so it would be good for you to know it basics at the first place. We wouldn’t copy-paste whole RFC 2616 and it recent updates there. Instead, we strongly RECOMMEND you to ackowledge with them. Above we’ll describe only parts of HTTP specification which TicketsCloud API is widely uses.

Request Methods

TicketsCloud uses the following HTTP request methods:

• GET

  Request the specified item.

• HEAD

  This method works like GET except that request with it doesn’t returns payload content.

• POST

  Create a new object or makes some action that doesn’t creates a new resource.

• PUT

  Used to update a specified resource or create a new one on the specified resource.

• DELETE

  Deletes the specified resource, destroys associated object or cancels some action.

• PATCH

  While PUT is used to update whole resource content, PATCH allows to update only certain fields without need to pass around all the data.

Request Headers

• Accept

  Specifies the list of accepted data types to be returned by the server (i.e. that are accepted/understandable by the client). The format should be a list of one or more MIME types, separated by colons.

  For the majority of requests the definition should be for JSON data (application/json).

  The use of Accept in requests is not required, but is highly recommended as it helps to ensure that the data returned can be processed by the client.

  If resource is unable to return the response in the accepted MIME type, the 406 Not Acceptable response will be returned instead.

• Authorization

  Specified authentication token by which the server can recognize the related user.

  TicketsCloud API uses custom authentication scheme named Key and custom unique token which users receives from TicketsCloud customers service.

  GET /v1/resources/events HTTP/1.1
  Accept: application/json
  Authorization: Key 6e6124cfc954496a850aa959ef2f64fa
  Host: ticketscloud.org
  

• Content-Type

  Specifies the content type of the information being supplied within the request. The specification uses MIME type specifications. For the majority of requests this will be JSON (application/json).

  The use of the Content-Type on a request is highly recommended.

Response Status Codes

With the interface to TicketsCloud working through HTTP, error codes and statuses are reported using a combination of the HTTP status code number, and corresponding data in the body of the response data.

A list of the error codes returned by TicketsCloud, and generic descriptions of the related errors are provided below. The meaning of different status codes for specific request types are provided in the corresponding API call reference.

• 200 OK

  Request completed successfully.

• 201 Created

  Resource object had been created successfully.

• 202 Accepted

  Request has been accepted, but the corresponding operation may not have completed. This is used for background operations, such as database compaction.

• 400 Bad Request

  Bad request structure. The error can indicate an error with the request URL, path, headers or payload data.

• 401 Unauthorized

  The item requested was not available using the supplied authorization, or authorization was not supplied.

• 403 Forbidden

  The requested item or operation is forbidden.

• 404 Not Found

  The requested content could not be found. The content will include further information, as a JSON object, if available.

• 405 Method Not Allowed

  A request was made using an invalid HTTP request type for the URL requested. For example, you have requested a PUT when a POST is required. Errors of this type can also triggered by invalid URL strings.

• 406 Not Acceptable

  The requested content type is not supported by the server.

• 409 Conflict

  Request resulted in an update conflict.

• 415 Unsupported Media Type

  The content types supported, and the content type of the information being requested or submitted indicate that the content type is not supported.

• 500 Internal Server Error

  The request was invalid, either because the supplied JSON was invalid, or invalid information was supplied as part of the request.

• 502 Bad Gateway

  Something really gone wrong.

Response Headers

Response headers are returned by the server when sending back content and include a number of different header fields, many of which are standard HTTP response header and have no significance to TicketsCloud operation. The list of response headers important to TicketsCloud are listed below.

• Content-Length

  The length (in bytes) of the returned content.

• Content-Type

  Specifies the MIME type of the returned data. For most request, the returned MIME type is text/plain. All text is encoded in Unicode (UTF-8), and this is explicitly stated in the returned Content-Type, as text/plain;charset=utf-8.

• Cache-Control

  The cache control HTTP response header provides a suggestion for client caching mechanisms on how to treat the returned information. TicketsCloud typically returns the must-revalidate, which indicates that the information should be revalidated if possible. This is used to ensure that the dynamic nature of the content is correctly updated.

Versioning

TicketsCloud HTTP API is versioned by using URL approach: the version is explicitly defined as path segment in the format v<num>. Version numeration is stated from 1 and grows one by one.

Within the same version we guarantee that everything will works as it was before.

In case of breaking changes in API, version number gets bumped.

JSON

The majority of requests and responses to TicketsCloud API uses the JavaScript Object Notation (JSON) for formatting the content and structure of the data and responses.

JSON is used because it is the simplest and easiest to use solution for working with data within a web browser, as JSON structures can be evaluated and used as JavaScript objects within the web browser environment.

JSON supports the same basic types as supported by JavaScript, these are:

• Number (either integer or floating-point).
• String; this should be enclosed by double-quotes and supports Unicode characters and backslash escaping. For example:

"A String"

• Boolean - a true or false value. You can use these strings directly. For example:

true

• Array - a list of values enclosed in square brackets. For example:

["one", "two", "three"]

• Object - a set of key/value pairs (i.e. an associative array, or hash). The key must be a string, but the value can be any of the supported JSON values.

Parsing JSON into a JavaScript object is supported through the JSON.parse() function in JavaScript, or through various libraries that will perform the parsing of the content into a JavaScript object for you. Libraries for parsing and generating JSON are available in many languages, including Perl, Python, Ruby, Erlang and others.

Fields Schema DSL

When we made a request to some resource, in most cases we don’t want all the data, just a small part of it. We receiving JSON object, picking the fields we’re interested in leaving every else for garbage collector.

TicketsCloud API provides a feature to receive only those fields you’re using special query parameter fields-schema. It accepts the special DSL value which uses as field filter on server side, returning an object with only specified fields.

For example, we need to receive our current user ID and email fields only:

Request:

GET /v1/services/whoami?fields-schema=id,email HTTP/1.1
Accept: application/json
Cookie: auth_tkt="FiYmQwNmIyMWNiMjU0!userid_type:b64unicode"; Domain=ticketscloud.org; Path=/
Host: ticketscloud.org

Response:

HTTP/1.1 200 OK
Connection: keep-alive
Content-Encoding: gzip
Content-Type: application/json; charset=UTF-8
Server: nginx
Transfer-Encoding: chunked

{
    "id": "53da11a537abbd06b21cb254",
    "email": "user@domain.tld"
}

You may freely specify any top level fields separated by comma as fields-schema value. In case if the value is incorrect, a 400 Bad Request response will be returned.