.. _api/basics:
==========
API Basics
==========
In this chapter you'll find HTTP API common bits about design and workflow.
.. _api/http:
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:
- :method:`GET`
Request the specified item.
- :method:`HEAD`
This method works like :method:`GET` except that request with it doesn't
returns payload content.
- :method:`POST`
Create a new object or makes some action that doesn't creates a new resource.
- :method:`PUT`
Used to update a specified resource or create a new one on the specified
resource.
- :method:`DELETE`
Deletes the specified resource, destroys associated object or cancels some
action.
- :method:`PATCH`
While :method:`PUT` is used to update whole resource content,
:method:`PATCH` allows to update only certain fields without need to pass
around all the data.
Request Headers
---------------
- :header:`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
(:mimetype:`application/json`).
The use of :mimetype:`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 :statuscode:`406` response will be returned instead.
- :header:`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.
.. code-block:: http
GET /v1/resources/events HTTP/1.1
Accept: application/json
Authorization: Key 6e6124cfc954496a850aa959ef2f64fa
Host: ticketscloud.org
- :header:`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 (:mimetype:`application/json`).
The use of the :header:`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.
- :statuscode:`200`
Request completed successfully.
- :statuscode:`201`
Resource object had been created successfully.
- :statuscode:`202`
Request has been accepted, but the corresponding operation may not
have completed. This is used for background operations, such as
database compaction.
- :statuscode:`400`
Bad request structure. The error can indicate an error with the
request URL, path, headers or payload data.
- :statuscode:`401`
The item requested was not available using the supplied
authorization, or authorization was not supplied.
- :statuscode:`403`
The requested item or operation is forbidden.
- :statuscode:`404`
The requested content could not be found. The content will include
further information, as a JSON object, if available.
- :statuscode:`405`
A request was made using an invalid HTTP request type for the URL
requested. For example, you have requested a :method:`PUT` when a
:method:`POST` is required. Errors of this type can also triggered
by invalid URL strings.
- :statuscode:`406`
The requested content type is not supported by the server.
- :statuscode:`409`
Request resulted in an update conflict.
- :statuscode:`415`
The content types supported, and the content type of the information
being requested or submitted indicate that the content type is not
supported.
- :statuscode:`500`
The request was invalid, either because the supplied JSON was
invalid, or invalid information was supplied as part of the request.
- :statuscode:`502`
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.
- :header:`Content-Length`
The length (in bytes) of the returned content.
- :header:`Content-Type`
Specifies the MIME type of the returned data. For most request, the
returned MIME type is :mimetype:`text/plain`. All text is encoded in Unicode
(UTF-8), and this is explicitly stated in the returned
:header:`Content-Type`, as :mimetype:`text/plain;charset=utf-8`.
- :header:`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.
.. _api/version:
Versioning
==========
TicketsCloud HTTP API is versioned by using URL approach: the version is
explicitly defined as path segment in the format ``v``. 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.
.. _api/json:
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:
.. code-block:: javascript
"A String"
- Boolean - a ``true`` or ``false`` value. You can use these strings
directly. For example:
.. code-block:: javascript
true
- Array - a list of values enclosed in square brackets. For example:
.. code-block:: javascript
["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.
.. _api/dsl:
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**:
.. sourcecode:: http
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**:
.. sourcecode:: http
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 :statuscode:`400`
response will be returned.