Skip to content

Allegro REST API Design Guidelines

The purpose of this document is to keep Allegro Public REST API implementations as consistent as possible. The document is addressed to developers who:

  • design REST APIs for micro-services
  • create applications that consume these APIs.

These guidelines apply to all REST APIs, in particular:

  • REST APIs that will provide resources exposed in Allegro REST API
  • other REST APIs that will be consumed by Allegro Mobile Applications

We publish this document in order to:

  • help you to understand the principles behind our REST API design if you are a developer/administrator who wants to interact with the API provided by Allegro Public REST API or micro-services,
  • ensure consistency between your service and the Allegro REST API if you are developing a service consuming a REST API,
  • hear your feedback.

Allegro REST API

Allegro REST API is a new API interface that will integrate the Allegro platform with:

  • third-party applications that use Allegro WebAPI at present,
  • Allegro Mobile Applications,
  • frontend / web applications.

We are providing you with Allegro REST API, while we try to deliver truly RESTful API interface with positive developer experience (DX).

Resources that will contribute to Allegro REST API will be provided by micro-services.

Each micro-service will provide its own REST API resources exposing the Allegro platform's specific functionality. The goal of these application-specific APIs is to share common design standards, as described herein.

What is RESTful API interface?

The REST architectural style describes six constraints. These constraints, applied to the architecture, were originally communicated by Roy Fielding in his doctoral dissertation (see http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm) and defines the basis of RESTful-style.

The six constraints are:

The uniform interface constraint is fundamental to the design of any REST service. The uniform interface simplifies and decouples the architecture, which enables each part to evolve independently.

The four constraints concerning uniform interface are:

Resource-Based

Individual resources are identified in requests, for example using URIs in web-based REST systems. The resources themselves are conceptually separate from the representations that are returned to the client. For example, the server may send data from its database as HTML, XML or JSON, none of which are the server's internal representation.

Manipulation of resources through these representations

When a client holds a representation of a resource, including any metadata attached, it has enough information to modify or delete the resource on the server, provided it has permission to do so.

Self-descriptive messages

Each message includes enough information to describe how to process the message. For example, which parser to invoke may be specified by an Internet media type (previously known as a MIME type). Responses also explicitly indicate their cache-ability.

Hypermedia as the engine of application state (HATEOAS)

Clients deliver state via body contents, query-string parameters, request headers and the requested URI (the resource name). Services deliver state to clients via body content, response codes, and response headers. This is technically referred to as hypermedia (or hyperlinks within hypertext). Aside from the description above, HATEOS also means that, where necessary, links are contained in the returned body (or headers) to supply the URI for retrieval of the object itself or related objects. We will talk about this in more detail later.

If a service violates any of the required constraints, it cannot be considered RESTful.

Complying with these constraints, and thus conforming to the REST architectural style, enables any kind of distributed hypermedia system to have desirable non-functional properties such as performance, scalability, simplicity, modifiability, visibility, portability, and reliability.

What is Developer Experience?

One of the key principles of good API design is that an interface must provide a seamless and user-friendly developer experience (DX) if it is to facilitate the creation of applications that add value to the API owner’s business.