API Conventions

RESTful Features

Xapiand uses a RESTful API exposed using JSON over HTTP.

When we talk about our API, we use terms like “REST” and “RESTful.” “REST” stands for Representational State Transfer.

The conventions listed in here can be applied throughout the REST API, unless otherwise specified.

RESTful HTTP Methods

You may see these standard HTTP methods referred to as CRUD, or Create, Read, Update, Delete. Although CRUD has roots in database operations, you can also map those operations to the standard HTTP methods. For example, use a POST request to create a new resource, a GET request to read or retrieve a resource, a PATCH or UPDATE request to edit a resource, and a DELETE request to delete a resource.

Deviations from REST

We do our best to use standard HTTP methods with accurate and well-known status codes in the Xapiand API, but here are some additions and deviations.

Additionally to the standard HTTP methods, we also use other custom methods such as UPDATE, for certain operations.

HTTP Methods

Safe Methods
Requests that use safe HTTP methods won’t alter a resource at all. Examples are GET, OPTIONS and HEAD.
Idempotent Methods
An idempotent HTTP method is a HTTP method that can be called many times without different outcomes. It would not matter if the method is called only once, twice or a hundred times over, the result should be the same. This only applies to the result, not the resource itself. Examples are DELETE, PUT.
Not Safe/Idempotent Methods
This are requests that will alter the resource and potentially end up with different results every time. Examples are POST.

Custom Methods

The Standard Methods, the ones we all are familiar with, have simpler and well-defined semantics but there is functionality that cannot be easily expressed via standard methods. Custom methods refer to such API methods.

Simply pass the required method as a non-standard HTTP method in the request.

Example:

INFO /some/resource/name

If your firewall rules don’t support non-standard HTTP methods like PATCH, UPDATE or DELETE, for example, you have two options:

Use HTTP Method Override
Use HTTP Method Mapping

HTTP Method Override

You can use the X-HTTP-Method-Override (or HTTP-Method-Override) header. Pass the method you want to use in the X-HTTP-Method-Override header and use the POST method.

Example:

POST /some/resource/name
X-HTTP-Method-Override: INFO

HTTP Method Mapping

Custom methods can use the following generic HTTP mapping: http://service.name:8880/some/resource/name:customMethod

To use method mappings pass the mapping in the URL and use HTTP POST verb since it has the most flexible semantics, except for methods serving as an alternative get or list which may use GET.

Example:

GET /some/resource/name:info

Resource Paths

To slash or not to slash

That is the question we hear often. Onward to the answers! Historically, it’s common for URLs with a trailing slash to indicate a directory, and those without a trailing slash to denote a file:

http://example.com/foo (without trailing slash, conventionally a file)
http://example.com/foo/ (with trailing slash, conventionally a directory)

Source: Google WebMaster Central Blog - To slash or not to slash

Trailing slashes are important

To us, trailing slashes are important to distinguish between a path to an Index (a directory) and a path to a Document (a file).

The following will delete a single document from index /some/resource/name, the document with ID name:

DELETE /some/resource/name

Whilst the next example will delete the whole index /some/resource/path/ with all its documents in it as well:

DELETE /some/resource/path/

JSON, MessagePack, and YAML

The Xapiand API can process JSON, MessagePack, or YAML objects. Choose the format with the request’s Content-Type header (application/json, application/x-msgpack, or application/x-yaml); JSON is the default when no Content-Type is given.

YAML

You can also send documents as YAML by setting the Content-Type to application/x-yaml. Xapiand parses the body into the same internal object it would from the equivalent JSON:

PUT /twitter/user/Jane?commit
Content-Type: application/x-yaml

name: Jane
age: 30
city: Turin

GET /twitter/user/Jane

Deviations from JSON

Comments

JSON can have C-style /* */ block or single line // comments. Comments are allowed everywhere in the JSON document.

Trailing Commas

JSON can have trailing commas.

Field Expansion

JSON or MessagePack fields in objects passed to Xapiand are expanded. For example, the following nested object:

{
  "contact": {
    "address": {
      "country": {
        "name": "Italy"
      }
    }
  }
}

Is equivalent to:

{
  "contact.address.country.name": "Italy"
}

Multiple Indexes

Most APIs that refer to an index parameter support execution across multiple indexes, using simple test1,test2,test3 notation.