Improve this page

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

The Method Override won’t work with any other method other than POST, you’ll receive an error.

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/

Remember
Trailing slashes in resource paths are important, always make sure you are requesting a method for the proper resource path. Trailing slashes do mean something.

---

JSON and MessagePack

The Xapiand API can process JSON objects or MessagePack objects.

MessagePack
MessagePack is more efficient and it is our internal representation of the data.

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 Indices

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

Single index APIs such as the Document APIs and the single-index alias APIs do not support multiple indices.

Back

Next