Allegro REST API Design Guidelines

The Allegro REST API Design Guidelines provide a standard for implementing consistent REST APIs across Allegro's micro-services ecosystem. These guidelines are intended for two primary groups:

1. API Designers: Developers creating micro-services that expose resources to the Allegro platform.
2. API Consumers: Developers building applications (Mobile, Web, or third-party) that consume Allegro APIs.

The goal is to ensure consistency between individual micro-services and the broader Allegro Public REST API, facilitating a positive Developer Experience (DX).

All date and time values must be accepted and returned in UTC only.

For full date and time, use the ISO8601 string format: yyyy-MM-dd'T'HH:mm:ss.SSSZ.

If you only need to represent a time without a date, use the format HH:mm:ss.SSS without any time zone information. Clients should present this value exactly as received. If a specific time zone is required for presentation, use a full UTC date and time instead.

{
  // Full date and time
  "createdAt": "2012-01-01T12:00:00.000Z",
  "updatedAt": "2012-01-01T13:00:00.000Z"
}

// Time without date
{
  "from": "08:00:00.000",
  "to": "16:00:00.000"
}

When designing or consuming resources, follow these naming and path conventions:

• Resource Names: Use plural versions of resource names (e.g., /users, /offers, /shipments).
• Path Formatting: Use lowercase and dash-separated names (e.g., /general-deliveries, /application-configurations).
• Identification: Use UUIDs as lowercase strings in 8-4-4-4-12 format (e.g., 01234567-89ab-cdef-0123-456789abcdef). Avoid auto-incrementing IDs.
• Nesting: Minimize nesting depth. Instead of deeply nested paths like /users/{userId}/offers/{offerId}/shipments/{shipmentId}, prefer locating resources at the root or using nesting only to indicate scoped collections (e.g., /offers/{offerId}/shipments).

Allegro does not use or support HATEOAS (Hypermedia as the Engine of Application State) in its REST API design.

While HATEOAS principles suggest that interaction with an endpoint should be defined via metadata within the output representation (allowing clients to discover available actions and state transitions via URLs), Allegro's design philosophy prioritizes the fact that API integration logic is typically determined at development time rather than at runtime.

Implementing HATEOAS would require significant changes to client-side logic (such as mobile applications), necessitating that URIs be included in domain model objects or that controller contracts be updated to include URIs alongside objects.

Avoid deeply nested paths like /users/{userId}/offers/{offerId}/shipments/{shipmentId}. Instead, prefer locating resources at the root path and using nesting only to indicate scoped collections. This improves scalability and simplifies resource access.

Recommended pattern:

• /users/{userId}
• /users/{userId}/offers
• /offers/{offerId}
• /offers/{offerId}/shipments
• /shipments/{shipmentId}

// Avoid this:
/users/{userId}/offers/{offerId}/shipments/{shipmentId}

// Prefer this:
/users/{userId}
/users/{userId}/offers
/offers/{offerId}
/offers/{offerId}/shipments
/shipments/{shipmentId}

To minimize disruption, complex changes are often split into smaller, safer steps. If you see multiple related changes appearing, they likely follow these patterns:

Endpoint Renaming

1. New endpoint is introduced.
2. Old endpoint is removed.

Response Body Field Renaming

1. New field is introduced.
2. Old field is removed.

Request Body Field Renaming

1. New optional field is introduced.
2. New optional field is made mandatory (Tightening input constraint).
3. Old field is made optional (Releasing input constraint).
4. Old field is removed.

Adding Mandatory Elements (Query param, request body field, or header)

1. New optional element is added.
2. Optional element is made required (Tightening input constraint).

When designing or consuming Allegro APIs, avoid these common mistakes:

• Using POST for commands: POST is not idempotent. Use PUT with a client-generated UUID in the URI to ensure business logic executes only once.
• Sending UUIDs in headers: This is incompatible with REST and the HTTP RFC (non-standard headers are deprecated). Put the UUID in the URI instead.
• Using picture: Always use image.
• Using metadata: Avoid this key; move information to the parent entity.
• Using page or pageIndex: Always use offset for pagination.
• HATEOAS: Allegro does not use or support HATEOAS.

The Synchronous Command Pattern is used for custom operations that cannot be expressed by a noun and an HTTP method, where the client expects an immediate response after the operation completes.

Key Characteristics:

• Method: Always uses POST.
• Suffix: The endpoint name must end with -commands.
• Idempotency: The request may optionally include an id attribute to ensure idempotency.
• Structure: Request and response bodies have no fixed structure.

Example: To modify multiple offer prices in a single call, use POST /modify-offer-prices-commands.

// POST /modify-offer-prices-commands
{
  "changeType": "INCREASE",
  "modificationValue": 15,
  "modificationUnit": "PERCENTAGE",
  "includedOffers": [
    "12345",
    "45678",
    "56789"
  ]
}