Zalando RESTful API and Event Guidelines

https://opensource.zalando.com/restful-api-guidelines
Admin
These guidelines provide a comprehensive set of rules and best practices for designing and...
Tokens:35,627
Snippets:515
Trust Score:9.9
Update:6 months ago
Show doc for...
Tokens:
Raw
### Resource Type Examples

Source: https://opensource.zalando.com/restful-api-guidelines

Illustrates how to categorize resources into types for API design. Different resource paths are shown as examples.

```plaintext
/customers
/customers/{id}
/customers/{id}/preferences
/customers/{id}/addresses
/customers/{id}/addresses/{addr}
/addresses
/addresses/{addr}
```

--------------------------------

### Define Array Schema with Example

Source: https://opensource.zalando.com/restful-api-guidelines

Schema definition for an array of strings with a specific example.

```yaml
schema:
  type: array
  items:
    type: string
style: simple
explode: false
example: [ "5db68c06-1a68-11e9-8341-68f728c1ba70", 'W/"xy", "5"' ]
```

--------------------------------

### Example Content-Encoding Header Values

Source: https://opensource.zalando.com/restful-api-guidelines

This example shows common values for the Content-Encoding header, used for indicating compression methods.

```text
["gzip", "deflate", "gzip,deflate"]
```

--------------------------------

### Deprecation and Sunset Header Examples

Source: https://opensource.zalando.com/restful-api-guidelines

Example values for Deprecation and Sunset headers using their respective time formats.

```text
Deprecation: @1758095283
Sunset: Wed, 31 Dec 2025 23:59:59 GMT
```

--------------------------------

### Normalize Request Paths

Source: https://opensource.zalando.com/restful-api-guidelines

Examples of equivalent request paths that should be normalized to the same resource.

```text
GET /orders/{order-id}
GET /orders/{order-id}/
GET /orders//{order-id}
```

--------------------------------

### Kebab-case path segment example

Source: https://opensource.zalando.com/restful-api-guidelines

Demonstrates the required kebab-case format for path segments in resource URLs.

```text
/shipment-orders/{shipment-order-id}
```

--------------------------------

### Define OpenAPI Meta Information

Source: https://opensource.zalando.com/restful-api-guidelines

Example of the required OpenAPI structure including version, title, and description fields.

```yaml
openapi: 3.1.0
info:
  version: 1.3.7
  title: Parcel Service API
  description: API for <...>
  <...>
```

--------------------------------

### Request Versioned Content

Source: https://opensource.zalando.com/restful-api-guidelines

Example of using the Accept header to request a specific version of a resource.

```http
Accept: application/x.zalando.cart+json;version=2
```

--------------------------------

### Create Article Lock Resource

Source: https://opensource.zalando.com/restful-api-guidelines

Example of using a PUT request to create a resource instead of using an action-based verb.

```http
PUT /article-locks/{article-id}
```

--------------------------------

### Kebab-Case Header Naming Examples

Source: https://opensource.zalando.com/restful-api-guidelines

Follow the kebab-case convention with uppercase separate words for consistency and readability.

```text
If-Modified-Since
Accept-Encoding
Content-ID
Language
```

--------------------------------

### Example API Audience Usage

Source: https://opensource.zalando.com/restful-api-guidelines

Implementation of the x-audience field within an OpenAPI info-block.

```yaml
openapi: 3.1.0
info:
  x-audience: company-internal
  title: Parcel Helper Service API
  description: API for <...>
  version: 1.2.4
  <...>
```

--------------------------------

### Content-Location Header Usage Example

Source: https://opensource.zalando.com/restful-api-guidelines

When using Content-Location, ensure the Content-Type header is also provided.

```http
GET /products/123/images HTTP/1.1

HTTP/1.1 200 OK
Content-Type: image/png
Content-Location: /products/123/images?format=raw
```

--------------------------------

### Unfiltered API Response Example

Source: https://opensource.zalando.com/restful-api-guidelines

This example demonstrates a full API response without any field filtering. It includes all available fields for a user resource.

```http
GET http://api.example.org/users/123 HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "cddd5e44-dae0-11e5-8c01-63ed66ab2da5",
  "name": "John Doe",
  "address": "1600 Pennsylvania Avenue Northwest, Washington, DC, United States",
  "birthday": "1984-09-13",
  "friends": [ { 
    "id": "1fb43648-dae1-11e5-aa01-1fbc3abb1cd0",
    "name": "Jane Doe",
    "address": "1600 Pennsylvania Avenue Northwest, Washington, DC, United States",
    "birthday": "1988-04-07"
  } ]
}
```

--------------------------------

### Example API Identifier Usage

Source: https://opensource.zalando.com/restful-api-guidelines

Implementation of the x-api-id field using a UUID within an OpenAPI info-block.

```yaml
openapi: 3.1.0
info:
  x-api-id: d0184f38-b98d-11e7-9c56-68f728c1ba70
  title: Parcel Service API
  description: API for <...>
  version: 1.5.8
  <...>
```

--------------------------------

### Define Event Type Ordering Fields

Source: https://opensource.zalando.com/restful-api-guidelines

Examples of JSON paths used to specify ordering fields within an event object.

```text
data.order_change_counter
```

```text
data.order_number
```

--------------------------------

### Permission Naming Convention Examples

Source: https://opensource.zalando.com/restful-api-guidelines

Illustrates typical permission names based on the defined schema, showing combinations of application ID, resource name, and access mode. APIs should generally prefer component-specific permissions without resource extensions.

```plaintext
Application ID | Resource ID | Access Type | Example  
---|---|---|---
`order-management` | `sales-order` | `read` | `order-management.sales-order.read`  
`order-management` | `shipment-order` | `read` | `order-management.shipment-order.read`  
`fulfillment-order` |  | `write` | `fulfillment-order.write`  
`business-partner-service` |  | `read` | `business-partner-service.read`  
```

--------------------------------

### Handling API Extensions in Java with Jackson

Source: https://opensource.zalando.com/restful-api-guidelines

Example of how to handle unknown optional fields in API resources using Jackson in Java. This allows clients to accept compatible API extensions by deserializing unknown fields into a Map.

```java
@JsonAnyGetter
@JsonAnySetter
private Map<String, JsonNode> additionalProperties = new HashMap<>();
```

--------------------------------

### OpenAPI Documentation for Implicit Filtering

Source: https://opensource.zalando.com/restful-api-guidelines

Example of documenting implicit filtering within an OpenAPI specification. This ensures consumers understand that the returned data is restricted based on authorization.

```yaml
paths:
  /business-partner:
    get:
      description: >-
        Get the list of registered business partner.
        Only the business partners to which you have access to are returned.
```

--------------------------------

### Standard Media Types for Content Negotiation

Source: https://opensource.zalando.com/restful-api-guidelines

Examples of standard media types to be used in the 'Accept' header for content negotiation. This allows clients to specify preferred resource representations.

```http
Accept: application/json
Accept: application/pdf
```

--------------------------------

### Declare Versioned Content-Type

Source: https://opensource.zalando.com/restful-api-guidelines

Example of using the Content-Type header to declare the version of the payload.

```http
Content-Type: application/x.zalando.cart+json;version=2
```

--------------------------------

### Example of Extended Hypertext Control for Spouse Relationship

Source: https://opensource.zalando.com/restful-api-guidelines

Illustrates an extended hypertext control object used to represent a 'spouse' relationship. It includes additional attributes like 'since', 'id', and 'name' to provide more context about the linked resource and the relationship.

```json
{
  "id": "446f9876-e89b-12d3-a456-426655440000",
  "name": "Peter Mustermann",
  "spouse": {
    "href": "https://...",
    "since": "1996-12-19",
    "id": "123e4567-e89b-12d3-a456-426655440000",
    "name": "Linda Mustermann"
  }
}
```

--------------------------------

### Example JSON object for a map definition

Source: https://opensource.zalando.com/restful-api-guidelines

A sample JSON structure representing the map defined in the schema.

```json
{ "message_key": "color",
  "translations": {
    "de": "Farbe",
    "en-US": "color",
    "en-GB": "colour",
    "eo": "koloro",
    "nl": "kleur"
  }
}
```

--------------------------------

### Implicit Filtering Example - FOO Company

Source: https://opensource.zalando.com/restful-api-guidelines

Demonstrates how implicit filtering affects the response for different clients. The API specification should clearly document such filtering to manage client expectations and caching.

```json
{
    "items": [
        { "name": "Foo Performance" },
        { "name": "Foo Sport" },
        { "name": "Foo Signature" }
    ]
}
```

--------------------------------

### Embed sub-resources via query parameters

Source: https://opensource.zalando.com/restful-api-guidelines

Example of using the embed query parameter to include sub-resources in a single response.

```http
GET /order/123?embed=(items) HTTP/1.1

{
  "id": "123",
  "_embedded": {
    "items": [
      {
        "position": 1,
        "sku": "1234-ABCD-7890",
        "price": {
          "amount": 71.99,
          "currency": "EUR"
        }
      }
    ]
  }
}
```

--------------------------------

### Standard Pagination Links

Source: https://opensource.zalando.com/restful-api-guidelines

Use standard hypertext controls for pagination, including self, first, previous, next, and last links. The 'query' object can be used as a request body for GET with body operations.

```json
{
  "self": "https://my-service.zalandoapis.com/resources?cursor=<self-position>",
  "first": "https://my-service.zalandoapis.com/resources?cursor=<first-position>",
  "prev": "https://my-service.zalandoapis.com/resources?cursor=<previous-position>",
  "next": "https://my-service.zalandoapis.com/resources?cursor=<next-position>",
  "last": "https://my-service.zalandoapis.com/resources?cursor=<last-position>",
  "query": {
    "query-param-<1>": ...,
    "query-param-<n>": ...
  },
  "items": [...] 
}
```

--------------------------------

### Define an extensible enumeration in OpenAPI

Source: https://opensource.zalando.com/restful-api-guidelines

Use the examples field to define an open-ended list of values for enumeration types, prefixing the description with [Extensible enum].

```yaml
delivery_method:
  type: string
  examples:
    - PARCEL
    - LETTER
    - EMAIL
  description: [Extensible enum](https://opensource.zalando.com/restful-api-guidelines/#112). The chosen delivery method of the invoice.
```

--------------------------------

### OpenAPI Parameter Definition for Accept-Encoding Header

Source: https://opensource.zalando.com/restful-api-guidelines

Defines the `Accept-Encoding` header in OpenAPI, specifying supported compression algorithms and client negotiation options. Includes examples of header values.

```yaml
components:
  parameters:
    Accept-Encoding:
        name: Accept-Encoding
        in: header
        required: false
        description: |-
          The **Accept-Encoding** indicates the content encoding (usually a
          compression algorithm) the client understands. The server selects one of
          the proposed encodings and returns his choice in the **Content-Encoding**
          response header.

          Supported compression algorithms of the server are [**gzip**][gzip] and
          **identity**, but other encodings from list below may be support too:

          * **gzip** - a compression format that uses [Lempel-Ziv coding][gzip]
            (LZ77) with a 32-bit CRC.
          * **compress** - a format using the [Lempel-Ziv-Welch][lzw] (LZW)
            algorithm.
          * **deflate** - A compression format that uses the [zlib][zlib] structure
            with the [deflate][deflate] compression algorithm.
          * **br** - a compression format that uses the [Brotli][brotli] algorithm.
          * **identity** - the identity function without modification or compression
            used to indicate unchanged responses. This value is always considered as
            acceptable, even if omitted.

          The server may choose not to compress the body of the response, if the
          identity value is acceptable, e.g. if the content is already compressed
          (e.g. for JPEG content), or if the server is missing resources to perform
          the compression operation.

          **Note:** A client is allowed to explicitly forbid the identity value by
          setting **identity;q=0** or **\*;q=0**, however, the server in return may
          respond with a **406** (Not Acceptable) error.

          See [RFC 9110 Section 12.5.3][rfc-9110-12.5.3] as well as [API Guideline
          Rule #156][api-156] for further details.

          [rfc-9110-12.5.3]: <https://tools.ietf.org/html/rfc9110#section-12.5.3>
          [api-156]: <https://opensource.zalando.com/restful-api-guidelines/#156>
          [gzip]: <https://en.wikipedia.org/wiki/LZ77_and_LZ78#LZ77>
          [lzw]: <https://en.wikipedia.org/wiki/LZW>
          [zlib]: <https://en.wikipedia.org/wiki/Zlib>
          [deflate]: <https://en.wikipedia.org/wiki/DEFLATE>
          [brotli]: <https://en.wikipedia.org/wiki/Brotli>
        schema:
          type: array
          items:
            type: string
        style: simple
        explode: false
        example: [ "gzip", "gzip;q=0.8,deflate;q=0.2", "gzip;q=0.9,identity;q=0" ]
```

--------------------------------

### POST for GET with Body Payload

Source: https://opensource.zalando.com/restful-api-guidelines

Use POST with a request body when GET with URL-encoded query parameters is not feasible. This example shows how to document such a scenario in OpenAPI.

```yaml
paths:
  /products:
    post:
      description: >
        [GET with body payload](https://opensource.zalando.com/restful-api-guidelines/#get-with-body)
        - no resources created: Returns all products matching the query passed
        as request input payload.
      requestBody:
        required: true
        content:
          ...
```

--------------------------------

### Historic x-extensible-enum Example

Source: https://opensource.zalando.com/restful-api-guidelines

This example shows the previous recommendation for defining extensible enums using the `x-extensible-enum` property in JSON schema. This approach is now deprecated.

```yaml
delivery_methods:
  type: string
  x-extensible-enum:
    - PARCEL
    - LETTER
    - EMAIL
  description: The chosen delivery method of the invoice.
```

--------------------------------

### Filtered API Response Example

Source: https://opensource.zalando.com/restful-api-guidelines

This example shows an API response filtered using the 'fields' query parameter to retrieve only specific fields. The 'fields' parameter allows clients to request a subset of data, reducing payload size.

```http
GET http://api.example.org/users/123?fields=(name,friends(name)) HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json

{
  "name": "John Doe",
  "friends": [ {
    "name": "Jane Doe"
  } ]
}
```

--------------------------------

### Correct Money Object Usage (Composition)

Source: https://opensource.zalando.com/restful-api-guidelines

Illustrates the preferred approach of using composition over inheritance for monetary values. This allows for flexibility, such as handling mixed currencies, and adheres to best practices.

```json
{
    "price": {
      "amount": 19.99,
      "currency": "EUR"
    },
    "discounted_price": {
      "amount": 9.99,
      "currency": "EUR"
    }
}
```

--------------------------------

### HTTP GET and PUT with Last-Modified/If-Unmodified-Since

Source: https://opensource.zalando.com/restful-api-guidelines

Demonstrates the use of Last-Modified and If-Unmodified-Since headers for optimistic locking during resource updates. The server rejects the PUT request with a 412 Precondition Failed status if the resource has been modified since the GET request.

```http
< GET /orders

> HTTP/1.1 200 OK
> Last-Modified: Wed, 22 Jul 2009 19:15:56 GMT
> {
>   "items": [
>     { "id": "O0000042", ... },
>     { "id": "O0000043", ... }
>   ]
> }

< PUT /block/O0000042
< If-Unmodified-Since: Wed, 22 Jul 2009 19:15:56 GMT
< { "id": "O0000042", ... }

> HTTP/1.1 204 No Content
```

```http
> HTTP/1.1 412 Precondition failed
```

--------------------------------

### Identify Resources and Sub-Resources via Path Segments

Source: https://opensource.zalando.com/restful-api-guidelines

Use path segments to identify resources and their sub-resources. Ensure that each sub-path is a valid reference to a resource or set of resources.

```plaintext
/resources/{resource-id}/sub-resources/{sub-resource-id}
```

```plaintext
/shopping-carts/de:1681e6b88ec1/items/1
```

```plaintext
/shopping-carts/de:1681e6b88ec1
```

```plaintext
/content/images/9cacb4d8
```

```plaintext
/content/images
```

--------------------------------

### Referencing Money Object in SalesOrder

Source: https://opensource.zalando.com/restful-api-guidelines

Example of how to reference the common Money object within another schema, such as SalesOrder. This promotes reusability and consistency.

```yaml
SalesOrder:
  properties:
    grand_total:
      $ref: 'https://opensource.zalando.com/restful-api-guidelines/models/money-1.0.0.yaml#/Money'
```

--------------------------------

### Implement Optimistic Locking with ETag and If-Match

Source: https://opensource.zalando.com/restful-api-guidelines

Requires an initial GET request to retrieve the ETag for a specific resource before performing a conditional PUT update.

```HTTP
< GET /orders

> HTTP/1.1 200 OK
> {
>   "items": [
>     { "id": "O0000042" },
>     { "id": "O0000043" }
>   ]
> }

< GET /orders/BO0000042

> HTTP/1.1 200 OK
> ETag: osjnfkjbnkq3jlnksjnvkjlsbf
> { "id": "BO0000042", ... }

< PUT /orders/O0000042
< If-Match: osjnfkjbnkq3jlnksjnvkjlsbf
< { "id": "O0000042", ... }

> HTTP/1.1 204 No Content
```

```HTTP
> HTTP/1.1 412 Precondition failed
```

--------------------------------

### Define API Hostname Patterns

Source: https://opensource.zalando.com/restful-api-guidelines

Specifies the syntax for functional and legacy application hostnames.

```text
<hostname>             ::= <functional-hostname> | <application-hostname>

<functional-hostname>  ::= <functional-name>.zalandoapis.com
```

```text
<application-hostname> ::= <application-id>.<organization-unit>.zalan.do
<application-id>       ::= [a-z][a-z0-9-]*  -- application identifier
<organization-id>      ::= [a-z][a-z0-9-]*  -- organization unit identifier, e.g. team identifier
```

--------------------------------

### Full OpenAPI Header Specification

Source: https://opensource.zalando.com/restful-api-guidelines

Detailed component definitions for Deprecation and Sunset headers including descriptions and schemas.

```yaml
components:
  headers:
    Deprecation:
        required: false
        description: |-
          The **Deprecation** response header (see [RFC 9745][rfc-9745]) announces
          an upcoming deprecation of a feature or resource. The deprecation value is
          either a timestamp as defined in [RFC 9651 Section 3.3.7][rfc-9651-3.3.7]
          or `true` - if the feature is already deprecated.

          The scope of the distinct deprecated feature or resource must be derived
          from the API spec. If the timestamp points to the past, the API spec also
          contains a migration advise.

          Clients should monitor the usage of **Deprecation** headers and notify
          about them in time, so that migration measures can be planned and executed
          timely (see also [API Guideline - Deprecation][api]).

          [rfc-9745]: <https://tools.ietf.org/html/rfc9745>
          [rfc-9651-3.3.7]: <https://tools.ietf.org/html/rfc9651#section-3.3.7>
          [api]: <https://opensource.zalando.com/restful-api-guidelines/#deprecation>
        schema:
          type: string
          format: date-timestamp
        example: "@1758093035"

    Sunset:
        required: false
        description: |-
          The **Sunset** response header (see [RFC 8594][rfc-8594]) communicates the
          point in time at which the feature or resource becomes unresponsive. The
          sunset value is providing a timestamp as defined in [RFC 9110 Section
          5.6.7][rfc-9110-5.6.7] usually pointing to the future. If a sunset value
          points to the past, the feature or resource must be expected to become
          unavailable at any time.

          Clients should monitor the usage of **Sunset** headers and warn/alert about
          them before the sunset time has come to take counter measures, e.g. prepare
          a client shutdown or migration (see also [API Guideline -
          Deprecation][api-deprecation]).

          [rfc-8594]: <https://tools.ietf.org/html/rfc8594>
          [rfc-9110-5.6.7]: <https://tools.ietf.org/html/rfc9110#section-5.6.7>
          [api-deprecation]: <https://opensource.zalando.com/restful-api-guidelines/#deprecation>
        schema:
          type: string
          format: http-date
        example: "Wed, 31 Dec 2025 23:59:59 GMT"
```

--------------------------------

### Define ETag, If-Match, If-None-Match Headers in OpenAPI

Source: https://opensource.zalando.com/restful-api-guidelines

Reference ETag, If-Match, and If-None-Match headers using external definitions in an OpenAPI specification.

```yaml
components:
  parameters|headers:
    ETag:
      $ref: 'https://opensource.zalando.com/restful-api-guidelines/models/headers-1.0.0.yaml#/ETag'
    If-Match:
      $ref: 'https://opensource.zalando.com/restful-api-guidelines/models/headers-1.0.0.yaml#/If-Match'
    If-None-Match:
      $ref: 'https://opensource.zalando.com/restful-api-guidelines/models/headers-1.0.0.yaml#/If-None-Match'
```

--------------------------------

### Define Tree Node Schema with Common Fields

Source: https://opensource.zalando.com/restful-api-guidelines

Example of a JSON schema implementing standard field naming conventions for identifiers, parent relationships, and timestamps.

```yaml
tree_node:
  type: object
  properties:
    id:
      description: the identifier of this node
      type: string
    parent_node_id:
      description: the identifier of the parent node of this node
      type: string
    created_at:
      description: when got this node created
      type: string
      format: 'date-time'
    modified_at:
      description: when got this node last updated
      type: string
      format: 'date-time'
  example:
    id: '123435'
    parent_node_id: '534321'
    created_at: '2017-04-12T23:20:50.52Z'
    modified_at: '2017-04-12T23:20:50.52Z'
```

--------------------------------

### Implicit Filtering Example - BAR Company

Source: https://opensource.zalando.com/restful-api-guidelines

Shows an alternative response when implicit filtering is applied, illustrating how data access restrictions are enforced per client.

```json
{
    "items": [
        { "name": "Bar Classics" },
        { "name": "Bar pour Elle" }
    ]
}
```
Tokens:
Raw