### Use `examples` for Extensible Enums (OpenAPI 3.1+)

Source: https://github.com/zalando/restful-api-guidelines/blob/main/chapters/compatibility.adoc

Use the `examples` property with a descriptive prefix to indicate an extensible enum. Consumers must be prepared for new values and implement fallback behavior.

```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.
```

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

### GET Request and Response Example with Last-Modified Header

Source: https://github.com/zalando/restful-api-guidelines/blob/main/chapters/best-practices.adoc

Demonstrates a GET request for orders and a successful HTTP response including the Last-Modified header, which is crucial for optimistic locking.

```http
< GET /orders

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

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

### Simple Query Parameters: Pagination

Source: https://github.com/zalando/restful-api-guidelines/blob/main/chapters/http-requests.adoc

Examples of query parameters for offset-based and keyset pagination.

```http
GET /items?offset=10&limit=5
```

```http
GET /items?limit=5&created_after=2019-07-17
```

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

### Simple Query Parameters: Less Than

Source: https://github.com/zalando/restful-api-guidelines/blob/main/chapters/http-requests.adoc

Examples of query parameters for filtering based on upper/lower bounds and time-specific terminology.

```http
GET /items?max_length=5
GET /items?shorter_than=5
```

```http
GET /items?price_lower_than=50
GET /items?price_lower_than_or_equal=50
```

```http
GET /items?created_before=2019-07-17
GET /items?active_until=2023-09-18T12:12:00.000Z
```

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

### Lint Code with Markdownlint

Source: https://github.com/zalando/restful-api-guidelines/blob/main/BUILD.adoc

Install and run markdownlint to check for coding standard violations. This is an experimental setup to enforce coding standards.

```bash
make lint
```

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

### Simple Query Parameters: More Than

Source: https://github.com/zalando/restful-api-guidelines/blob/main/chapters/http-requests.adoc

Examples of query parameters for filtering based on upper/lower bounds and time-specific terminology.

```http
GET /items?min_length=2
```

```http
GET /items?created_after=2019-07-17
GET /items?modified_since=2019-07-17
```

```http
GET /items?price_higher_than=50
GET /items?price_equal_or_higher_than=50
```

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

### Query Parameter Sorting Example

Source: https://github.com/zalando/restful-api-guidelines/blob/main/chapters/urls.adoc

Demonstrates how to use the `sort` query parameter to specify ascending or descending order for resource collections, using `+` for ascending and `-` for descending.

```http
/sales-orders?sort=+id
```

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

### Hypertext Control Example with Relationship

Source: https://github.com/zalando/restful-api-guidelines/blob/main/chapters/hyper-media.adoc

Illustrates a 'Person' resource representation using a hypertext control ('spouse') to link to another resource and describe 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 Concrete URL Paths

Source: https://github.com/zalando/restful-api-guidelines/blob/main/chapters/urls.adoc

Illustrates valid and intuitive URL paths for accessing resources and sub-resources, including shopping carts, items, and content images.

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

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

```http
/content/images/9cacb4d8
```

```http
/content/images
```

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

### HTTP GET and PUT with ETag for Optimistic Locking

Source: https://github.com/zalando/restful-api-guidelines/blob/main/chapters/best-practices.adoc

Demonstrates using GET to retrieve an entity with its ETag, followed by a PUT request including the If-Match header to ensure optimistic locking. A 412 Precondition Failed response indicates a conflict.

```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
```

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

### Simple Query Parameters: Equality

Source: https://github.com/zalando/restful-api-guidelines/blob/main/chapters/http-requests.adoc

Examples of query parameters used for filtering based on property equality and multiple choices.

```http
GET /items?name=Zalando
GET /items?creation_year=2023
GET /items?updated_by=user1
```

```http
GET /items?created_at=2023-09-18T12:12:00.000Z
GET /items?age=18
```

```http
GET /items?color=red,green,blue,multicolored
```

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

### Correct Money Representation Examples

Source: https://github.com/zalando/restful-api-guidelines/blob/main/chapters/json-guidelines.adoc

Examples of correct money representations, emphasizing the need for exact formats and avoiding float/double types to maintain precision.

```text
42.20 or 42.2 = 42 Euros, 20 Cent
0.23 = 23 Cent
42.0 or 42 = 42 Euros
1024.42 = 1024 Euros, 42 Cent
1024.4225 = 1024 Euros, 42.25 Cent
```

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

### Nested vs. Top-Level Resource URL Examples

Source: https://github.com/zalando/restful-api-guidelines/blob/main/chapters/urls.adoc

Illustrates the difference between nested URLs for sub-resources tightly coupled to a parent and top-level URLs for directly accessible resources.

```http
/shoping-carts/de/1681e6b88ec1/cart-items/1
```

```http
/customers/1637asikzec1
```

```http
/sales-orders/5273gh3k525a
```

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

### OpenAPI Example with x-audience

Source: https://github.com/zalando/restful-api-guidelines/blob/main/chapters/meta-information.adoc

An example of an OpenAPI specification snippet showing the `x-audience` field set to 'company-internal'.

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

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

### JSON Schema Example for Address Fields

Source: https://github.com/zalando/restful-api-guidelines/blob/main/chapters/json-guidelines.adoc

This YAML schema defines common fields for an address structure, including salutation, first name, and last name. It specifies the expected data types and provides examples.

```yaml
addressee:
  description: a (natural or legal) person that gets addressed
  type: object
  properties:
    salutation:
      description: |
        a salutation and/or title used for personal contacts to some
        addressee; not to be confused with the gender information!
      type: string
      example: Mr
    first_name:
      description: |
        given name(s) or first name(s) of a person; may also include the
        middle names.
      type: string
      example: Hans Dieter
    last_name:
      description: |
        family name(s) or surname(s) of a person
      type: string
      example: Mustermann
```

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

### Proprietary Zalando Header Examples

Source: https://github.com/zalando/restful-api-guidelines/blob/main/chapters/http-headers.adoc

Examples of proprietary Zalando headers used for passing generic context information end-to-end across service call chains.

```text
X-Flow-ID: GKY7oDhpSiKY_gAAAABZ_A
```

```text
X-Tenant-ID: 9f8b3ca3-4be5-436c-a847-9cd55460c495
```

```text
X-Sales-Channel: 52b96501-0f8d-43e7-82aa-8a96fab134d7
```

```text
X-Frontend-Type: mobile-app
```

```text
X-Device-Type: 
```

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

### Resource Type Example: Customers and Addresses

Source: https://github.com/zalando/restful-api-guidelines/blob/main/chapters/urls.adoc

Shows how related resources like customers, their preferences, addresses, and specific addresses are structured within an API, defining what constitutes a 'resource type'.

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

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

### POST for GET with Body Payload

Source: https://github.com/zalando/restful-api-guidelines/blob/main/chapters/http-requests.adoc

Use POST with a request body when GET with URL-encoded query parameters is not feasible for complex structured request information. This example shows the OpenAPI/YAML structure for such a scenario.

```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:
          ...
```

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

### Client Request for Specific Media Type Version

Source: https://github.com/zalando/restful-api-guidelines/blob/main/chapters/compatibility.adoc

Example of an HTTP Accept header used by a client to request a specific version of a media type.

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

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

### Get Article Size Advices by SKUs and Sales Channel

Source: https://github.com/zalando/restful-api-guidelines/blob/main/chapters/urls.adoc

Retrieves a list of article size advices by providing multiple SKUs and a sales channel ID as query parameters.

```APIDOC
## GET /article-size-advices?skus=sku-1,sku-2&sales_channel_id=sid-1

### Description
Retrieves a list of article size advices based on provided SKUs and a sales channel ID.

### Method
GET

### Endpoint
/article-size-advices

#### Query Parameters
- **skus** (string) - Required - Comma-separated list of article SKUs.
- **sales_channel_id** (string) - Required - The ID of the sales channel.

### Response
#### Success Response (200)
- **items** (array) - A list of article size advice objects.
  - **id** (string) - The unique identifier for the article size advice.
  - **...** (object) - Other relevant details about the article size advice.
```

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

### OpenAPI Info Object with x-api-id

Source: https://github.com/zalando/restful-api-guidelines/blob/main/chapters/meta-information.adoc

Example of an OpenAPI `info` object including the mandatory `x-api-id` extension for unique API identification.

```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
  <...>
```

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

### Unfiltered User Response (HTTP)

Source: https://github.com/zalando/restful-api-guidelines/blob/main/chapters/performance.adoc

An example of a full HTTP response for a user resource without any field filtering.

```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"
  } ]
}
```

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

### Resource Embedding Example

Source: https://github.com/zalando/restful-api-guidelines/blob/main/chapters/performance.adoc

Demonstrates how to use the 'embed' query parameter to include sub-resources in an API response. This reduces the number of client requests by fetching related data in a single call.

```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"
        }
      }
    ]
  }
}
```

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

### Generate Custom CSS

Source: https://github.com/zalando/restful-api-guidelines/blob/main/BUILD.adoc

This script clones the stylesheet-factory repository, installs dependencies, and generates custom CSS based on zalando.scss. It uses asciidoctor's stylesheet-factory for this process.

```bash
.scripts/build-css.sh
```

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

### Get Article Size Advice by ID

Source: https://github.com/zalando/restful-api-guidelines/blob/main/chapters/urls.adoc

Retrieves a specific article size advice using its unique resource identifier.

```APIDOC
## GET /article-size-advices/id-1

### Description
Retrieves a specific article size advice using its unique identifier.

### Method
GET

### Endpoint
/article-size-advices/{id}

#### Path Parameters
- **id** (string) - Required - The unique identifier of the article size advice.

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the article size advice.
- **sku** (string) - The SKU of the article.
- **sales_channel_id** (string) - The ID of the sales channel.
- **size** (object) - Details about the size recommendation.
- **...** (object) - Other relevant details about the article size advice.
```

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

### Compound Key as Mandatory Request Field Example

Source: https://github.com/zalando/restful-api-guidelines/blob/main/chapters/urls.adoc

Demonstrates how compound key components are passed as mandatory fields in a POST request and how the response includes an opaque identifier for the compound key.

```http
POST /article-size-advices { "sku": "sku-1", "sales_channel_id": "sid-1", "size": ... }
=> { "id": "id-1", "sku": "sku-1", "sales_channel_id": "sid-1", "size": ... }
```

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

### Filtered User Response with Fields Parameter (HTTP)

Source: https://github.com/zalando/restful-api-guidelines/blob/main/chapters/performance.adoc

An example of an HTTP response for a user resource filtered to include only specific fields and nested fields.

```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"
  } ]
}
```

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

### Filtered JSON Response (FOO Consumer)

Source: https://github.com/zalando/restful-api-guidelines/blob/main/chapters/http-requests.adoc

Example of a JSON response showing only business partners accessible to a consumer from company FOO. This illustrates implicit filtering based on access rights.

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

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

### Server Response/Client Request with Specific Media Type Version

Source: https://github.com/zalando/restful-api-guidelines/blob/main/chapters/compatibility.adoc

Example of an HTTP Content-Type header used by a server to declare the version of the media type it is sending, or by a client to send a request with a specific version.

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

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

### Vary Header for Proxy Caching with Media Type Versioning

Source: https://github.com/zalando/restful-api-guidelines/blob/main/chapters/compatibility.adoc

Example of an HTTP Vary header indicating that responses differ based on the Content-Type, crucial for proxy caches when using media type versioning.

```http
Vary: Content-Type
```

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

### Build and Test HTML Site

Source: https://github.com/zalando/restful-api-guidelines/blob/main/BUILD.adoc

Run this command to build and test the HTML version of the documentation site. The epub and pdf targets are also available for experimentation.

```bash
make all
```

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

### Example JSON Object for Map Definition

Source: https://github.com/zalando/restful-api-guidelines/blob/main/chapters/json-guidelines.adoc

An example JSON object illustrating a map structure where keys are language tags and values are translated strings, as defined by the OpenAPI schema using `additionalProperties`.

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

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

### Rate Limiting with X-RateLimit Headers

Source: https://github.com/zalando/restful-api-guidelines/blob/main/chapters/http-status-codes-and-errors.adoc

Demonstrates the use of X-RateLimit headers to provide details about request limits, remaining requests, and when the limit resets.

```http
HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 120
```

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

### Create Article Size Advice

Source: https://github.com/zalando/restful-api-guidelines/blob/main/chapters/urls.adoc

This endpoint is used to create a new article size advice. It requires a compound key composed of SKU, sales channel ID, and size as mandatory request fields.

```APIDOC
## POST /article-size-advices

### Description
Creates a new article size advice with provided compound key components.

### Method
POST

### Endpoint
/article-size-advices

### Request Body
- **sku** (string) - Required - The stock keeping unit.
- **sales_channel_id** (string) - Required - The identifier for the sales channel.
- **size** (string) - Required - The size of the article.

### Request Example
```json
{
  "sku": "sku-1",
  "sales_channel_id": "sid-1",
  "size": "M"
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the created article size advice.
- **sku** (string) - The stock keeping unit.
- **sales_channel_id** (string) - The identifier for the sales channel.
- **size** (string) - The size of the article.

#### Response Example
```json
{
  "id": "id-1",
  "sku": "sku-1",
  "sales_channel_id": "sid-1",
  "size": "M"
}
```
```

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

### Nested vs. Top-Level Resources

Source: https://github.com/zalando/restful-api-guidelines/blob/main/chapters/urls.adoc

Illustrates the recommended URL structures for resources, distinguishing between nested sub-resources and top-level resources based on accessibility and lifecycle coupling.

```APIDOC
## Resource URL Structures

### Nested Sub-Resource Example
Use nested URLs when a sub-resource is only accessible via its parent and may not exist without it.

```http
/shoping-carts/de/1681e6b88ec1/cart-items/1
```

### Top-Level Resource Example
Expose resources as top-level if they can be accessed directly via their unique ID, even if they are related to a parent resource.

```http
/customers/1637asikzec1
/sales-orders/5273gh3k525a
```
```

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

### Problem JSON Structure (OpenAPI Schema)

Source: https://github.com/zalando/restful-api-guidelines/blob/main/chapters/http-status-codes-and-errors.adoc

An example of an OpenAPI schema definition for a Problem JSON object, used for standardized error reporting.

```yaml
openapi: 3.0.0
info:
  version: 1.0.0
  title: Problem Details
paths:
  /:
    get:
      summary: Example endpoint returning Problem JSON
      responses:
        '400':
          description: Bad Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
components:
  schemas:
    Problem:
      type: object
      properties:
        type:
          type: string
          format: url
          description: A URI identifier for the problem type.
        title:
          type: string
          description: A short, human-readable summary of the problem.
        status:
          type: integer
          format: int32
          description: The HTTP status code generated by the origin server for this occurrence of the problem.
        detail:
          type: string
          description: An application-specific human-readable explanation of the problem.
        instance:
          type: string
          format: url
          description: A URI identifying this specific occurrence of the problem.
      required:
        - type
        - title
        - status
```

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

### Watch for Changes and Rebuild

Source: https://github.com/zalando/restful-api-guidelines/blob/main/BUILD.adoc

Use this command to watch for changes in .adoc and .css files and automatically rebuild the HTML site on save. It utilizes watchexec for efficient file monitoring.

```bash
make watch
```

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

### 202 Accepted

Source: https://github.com/zalando/restful-api-guidelines/blob/main/chapters/http-status-codes-and-errors.adoc

The request was successful and will be processed asynchronously. This is applicable to methods that change something, excluding GET methods that indicate asynchronous resource creation.

```APIDOC
## 202 Accepted

### Description
The request was successful and will be processed asynchronously. This is applicable to methods that change something, excluding GET methods that indicate asynchronous resource creation.

### Method
POST, PUT, PATCH, DELETE

### Response
#### Success Response (202)
- No specific payload is typically returned, as the processing is asynchronous.
```

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

### Exposing Compound Keys in Resource Identifiers

Source: https://github.com/zalando/restful-api-guidelines/blob/main/chapters/urls.adoc

Shows how to expose compound keys directly in resource paths, allowing for natural key representation instead of technical identifiers. This approach requires consistent abstraction in parameters and attributes.

```http
/resources/{compound-key-1}[delim-1]...[delim-n-1]{compound-key-n}
```

```http
/shopping-carts/{country}/{session-id}
```

```http
/shopping-carts/{country}/{session-id}/items/{item-id}
```

```http
/api-specifications/{docker-image-id}/apis/{path}/{file-name}
```

```http
/api-specifications/{repository-name}/{artifact-name}:{tag}
```

```http
/article-size-advices/{sku}/{sales-channel}
```

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

### Avoid actions in URLs; use HTTP methods

Source: https://github.com/zalando/restful-api-guidelines/blob/main/chapters/urls.adoc

URLs should describe resources (nouns), not actions (verbs). Use HTTP methods like PUT or POST to indicate operations on resources.

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

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

### Use `x-extensible-enum` for Extensible Enums (Historic)

Source: https://github.com/zalando/restful-api-guidelines/blob/main/chapters/compatibility.adoc

Historically, the `x-extensible-enum` extension was used to define extensible enums. This approach is now superseded by the `examples` property for OpenAPI 3.1+.

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

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

### API Specification for Filtered Endpoint

Source: https://github.com/zalando/restful-api-guidelines/blob/main/chapters/http-requests.adoc

Example of an OpenAPI specification (YAML) for the '/business-partner' endpoint. It documents that only business partners with access are returned, clarifying the implicit filtering behavior.

```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.
```

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

### Using Content-Location Header

Source: https://github.com/zalando/restful-api-guidelines/blob/main/chapters/http-headers.adoc

Demonstrates the use of the Content-Location header to specify a more specific identifier for a resource, often used with content negotiation. Requires Content-Type to be set as well.

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

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

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

### Define Custom Problem Type Schema

Source: https://github.com/zalando/restful-api-guidelines/blob/main/chapters/http-status-codes-and-errors.adoc

Example of referencing a custom problem type schema within an OpenAPI response definition. This allows for detailed, API-specific error information.

```yaml
responses:
  503:
    description: Service Unavailable
    content:
      "application/problem+json":
        schema:
          $ref: 'https://opensource.zalando.com/restful-api-guidelines/models/problem-1.0.1.yaml#/Problem'
```

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

### Referencing Standard Headers in OpenAPI

Source: https://github.com/zalando/restful-api-guidelines/blob/main/chapters/http-headers.adoc

Demonstrates how to reference standard HTTP headers like ETag within an OpenAPI specification using $ref. This approach simplifies API definitions by reusing common header models.

```yaml
path:
  '/resource'
    get:
      parameters:
        - $ref: '#/components/parameters/ETag'

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

  responses:
    Default:
      headers:
        ETag:
          $ref: '#/components/(parameters|headers)/ETag'
```

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

### JSON Schema Example for Tree Node

Source: https://github.com/zalando/restful-api-guidelines/blob/main/chapters/json-guidelines.adoc

This YAML schema defines properties for a tree node, including its ID, parent ID, and creation/modification timestamps. It specifies that IDs should be strings.

```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'
```

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

### Standard HTTP Header Naming Convention

Source: https://github.com/zalando/restful-api-guidelines/blob/main/chapters/http-headers.adoc

Illustrates the recommended kebab-case convention for HTTP headers, with separate words capitalized. This convention enhances readability and consistency, aligning with most standard headers.

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

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

### 304 Not Modified

Source: https://github.com/zalando/restful-api-guidelines/blob/main/chapters/http-status-codes-and-errors.adoc

Indicates that a conditional GET or HEAD request would have resulted in a 200 OK response, if it were not for the fact that the condition evaluated to false. For PUT/PATCH/DELETE requests, use 412 instead.

```APIDOC
## 304 Not Modified

### Description
Indicates that a conditional GET or HEAD request would have resulted in a 200 OK response, if it were not for the fact that the condition evaluated to false. For PUT/PATCH/DELETE requests, use 412 instead.

### Method
GET, HEAD

### Response
#### Success Response (304)
- No response body is returned.
```

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

### OPTIONS Request to Inspect Operations

Source: https://github.com/zalando/restful-api-guidelines/blob/main/chapters/http-requests.adoc

Use OPTIONS requests to discover the available HTTP methods for a given endpoint. Responses typically include an 'Allow' header or link templates.

```http
OPTIONS /resource
```

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

### Complex Query Language using JSON

Source: https://github.com/zalando/restful-api-guidelines/blob/main/chapters/http-requests.adoc

An example of a structured query using nested JSON data for complex filtering criteria, including logical operators like 'and' and 'or'.

```json
{
  "and": {
    "name": {
      "match": "Alice"
    },
    "age": {
      "or": {
        "range": {
          ">": 25,
          "<=": 50
        },
        "=": 65
      }
    }
  }
}
```

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

### Naming Convention for Date/Time Properties

Source: https://github.com/zalando/restful-api-guidelines/blob/main/chapters/json-guidelines.adoc

Name date and date-time properties to include type indicators like 'date', 'day', 'time', 'timestamp', or end with the '_at' suffix. This aids in distinguishing them from other property types.

```text
created_at, modified_at, occurred_at, returned_at
```

```text
campaign_start_time, arrival_date, checkout_time
```