API Reference
API Reference

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.

Exploring the API with Postman

If you haven't installed Postman yet, you can download it from Postman's official website. Follow the installation instructions specific to your operating system.

Importing the Xentral API specification

  1. Launch Postman and create a new workspace or select an existing one.
  2. Click on the Import button, typically found at the top-left corner.
  3. Choose the Link tab.
  4. In the URL field, paste the following URL: https://raw.githubusercontent.com/xentral/api-spec-public/main/openapi/xentral-api.openapi-3.0.0.json
  5. Click Import to load our Xentral API specification into Postman.

Configuring the Xentral API Collection

Once the API specification is imported, Postman will create a new collection named 'Xentral API'. You can now explore the various endpoints and methods available in our API.

Making API requests

With the Xentral API collection loaded, you can start making API requests:

  1. Select an endpoint from the 'Xentral API' collection.
  2. Click on the Send button to execute the request.
  3. Review the response in the 'Response' section below.

That's it! You're now ready to use our Xentral API with Postman. For more details on working with OpenAPI specifications in Postman, refer to Postman's official documentation. Happy coding!

Feedback

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

Xentral Website: https://xentral.com