Introduction

This page will help you get started with the Xentral API.

The Xentral Admin API utilizes the capabilities of the HTTP protocol and strongly focuses on resources and media types as its building blocks. Resources are modeled after important concepts in the application, such as Products, Users, Customers, Suppliers, Warehouse and others. They are exposed in the API through representations, where each representation provides the most useful way to interact with the resource within a certain use case. Each representation is assigned to the resource through its media type.
We conform to the HTTP/1.1 protocol as described in IETF RFCs 7230-7235 unless explicitly stated otherwise. We may also use transport-level optimizations from HTTP/2 as described in IETF RFC 7540.

Getting started with the API

To get started right away with the API, you can use the Xentral OpenAPI spec: https://github.com/xentral/api-spec-public

Standard API

If you need the (legacy) standard API, you can find the documentation here: https://update.xentral.biz/apidoc/docs211.html, and a postman collection in the same GitHub repository: https://github.com/xentral/api-spec-public

Calling convention

When calling the API the client picks up a resource, proper HTTP method and media types matching the expected operation result. The client then sends a request to the API and it replies with the response or returns a contextual error.

There are two headers that are used to communicate intent when calling the API:

Content-Type describes the request payload semantics, ie. the meaning of the data sent in the request,

Accept describes the response body semantics, ie. the meaning of the data sent back in the response.

The general rule of thumb about picking an HTTP method is described below:

POST results in the creation of the new resource of a given type,

GET returns given resource’s representation without any side effects,

PATCH partially or fully changes the state of a given resource,

PUT replaces or creates a new resource (upsert) when it does not exist (usage of this method is discouraged, as we should prefer POST and PATCH)

DELETE removes or hides a given resource making it inaccessible.

Responses

All responses will conform to the following base contract:

{
    "meta": {},
    "data": {},
    "extra": {},
    "links": {}
}

The keys returned in this response have the following purpose:

  • meta (optional)-> may contain information about the request (status code, media type, etc.)
  • data -> contains the actual response information (requested representation). If the API responds with a collection the data field will be an array ([]).
  • extra (optional)-> contains any additional information related to the response which is not a semantic part of the representation (pagination, total count, summaries, etc.)
  • links (optional) -> contains information about other resources and actions linked to a given resource which can be fetched by following the link.

Feedback

For any feedback about the Xentral API, you can reach us at api[at]xentral.com

Xentral Website: https://xentral.com