### Default User-Agent Example 1

Source: https://github.com/allegro/restapi-guideline/blob/master/docs/Resource.md

This is a default User-Agent string example.

```text
User-Agent: Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Iron/35.0.1900.0 Chrome/35.0.1900.0 Safari/537.36
```

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

### Default User-Agent Example 2

Source: https://github.com/allegro/restapi-guideline/blob/master/docs/Resource.md

This is another default User-Agent string example.

```text
User-Agent: Mozilla/5.0 (Linux; U; Android 2.2.1; en-us; Nexus One Build/FRG83) AppleWebKit/533.1 (KHTML, like Gecko) Version/4.0 Mobile Safari/533.1
```

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

### Query Pattern Example

Source: https://github.com/allegro/restapi-guideline/blob/master/adr/ADR-002-public-endpoint-name-must-be-a-noun.md

Demonstrates how to use the Query Pattern for advanced queries that cannot be expressed by a noun and GET method, or have complicated query attributes. It uses an HTTP POST method to a `-queries` suffixed endpoint.

```APIDOC
## POST /find-cheapest-offer-queries

### Description
Endpoint to find the cheapest offer fulfilling specific criteria, used when the number of parameters makes a GET request impractical.

### Method
POST

### Endpoint
/find-cheapest-offer-queries

### Request Body
- **category** (string) - Optional - Criteria for the offer category.
- **state** (string) - Optional - The state of the offer (e.g., "new").
- **stock** (object) - Optional - Stock availability details.
  - **available** (integer) - Required - Number of available units.
  - **unit** (string) - Required - The unit of stock (e.g., "UNIT").
- **marketplaces** (array) - Optional - List of marketplaces to search within.
  - (string) - Example: "allegro-pl"
- **delivery** (object) - Optional - Delivery options.
  - **carrier** (string) - Required - The delivery carrier.
  - **handlingTime** (string) - Required - The handling time (e.g., "PT24H").
- **payments** (object) - Optional - Payment options.
  - **invoice** (string) - Required - Invoice type (e.g., "VAT").

### Request Example
```json
{
  "category": "",
  "state": "new",
  "stock": {
    "available": 7,
    "unit": "UNIT"
  },
  "marketplaces": [
    "allegro-pl",
    "allegro-cz"
  ],
  "delivery": {
    "carrier": "UPS",
    "handlingTime": "PT24H"
  },
  "payments": {
    "invoice": "VAT"
  }
}
```

### Response
#### Success Response (200)
- **offerId** (string) - The ID of the cheapest offer found.
```

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

### Submitting Price and Currency via GET Request

Source: https://github.com/allegro/restapi-guideline/blob/master/docs/Representation.md

When submitting price and currency in a GET request, append them as query parameters. Ensure the 'Accept' header is set correctly.

```bash
curl https://api.allegro.pl/contests?totalAmount.amount=11.25&totalAmount.currency=PLN  \
    -H "Accept: application/vnd.allegro.public.v1+json"
```

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

### JSON Response Body Example

Source: https://github.com/allegro/restapi-guideline/blob/master/docs/Representation.md

Example of a JSON response body for a user resource.

```json
{
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "name": "user-name",
  "// ..."
}
```

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

### Query Pattern Example: Find Cheapest Offer

Source: https://github.com/allegro/restapi-guideline/blob/master/adr/ADR-002-public-endpoint-name-must-be-a-noun.md

Use the Query Pattern with a POST request to endpoints ending in '-queries' for advanced queries with complex attributes that cannot be handled by GET. This pattern is assumed to be safe and not alter server state.

```json
POST /find-cheapest-offer-queries
{
  "category": "",
  "state": "new",
  "stock": {
    "available": 7,
    "unit": "UNIT"
  },
  "marketplaces": [
    "allegro-pl",
    "allegro-cz"
  ],
  "delivery": {
    "carrier": "UPS",
    "handlingTime": "PT24H"
  },
  "payments": {
    "invoice": "VAT"
  }
}
```

```json
{
  "offerId": "1234"
}
```

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

### List Users with GET

Source: https://github.com/allegro/restapi-guideline/blob/master/docs/Resource.md

Use GET to retrieve a list of users. The server responds with HTTP 200 Ok and presents the collection as an array within a field named after the resource.

```bash
curl https://api.allegro.pl/users -H "Accept: application/vnd.allegro.public.v1+json"
```

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

### GET Request for Asynchronous Command Status Check

Source: https://github.com/allegro/restapi-guideline/blob/master/adr/ADR-002-public-endpoint-name-must-be-a-noun.md

This is an example of a GET request to check the status of an asynchronous command. The command ID obtained from the initial POST request is appended to the endpoint URL.

```http
GET /modify-offer-prices-commands/1b172506-1bec-11ee-be56-0242ac120002
```

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

### Get User by ID with GET

Source: https://github.com/allegro/restapi-guideline/blob/master/docs/Resource.md

Use GET with a user ID to retrieve a specific user entity. The server responds with HTTP 200 Ok and the entity in the established version.

```bash
curl https://api.allegro.pl/users/{id} -H "Accept: application/vnd.allegro.public.v1+json"
```

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

### Flat Structure Example (Avoid)

Source: https://github.com/allegro/restapi-guideline/blob/master/docs/Representation.md

Avoid flat structures for related resources; prefer nested objects for better extensibility.

```json
{
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "name": "offer-name",
  "sellerId": "5d8201b0...",
  "sellerName": "user-name"
  "// ..."
}
```

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

### Command Status Response - SUCCESSFUL

Source: https://github.com/allegro/restapi-guideline/blob/master/docs/Command pattern.md

Example response indicating a command has successfully completed. Includes input data and status.

```javascript
200 Ok
{
    "status" : "SUCCESSFUL",
    "fromDate" : "2015-08-30T17:00:00.000Z",
    "duration" : "P7D",
    // other output data given to this command
}
```

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

### Pretty-Printed JSON Response Example

Source: https://github.com/allegro/restapi-guideline/blob/master/docs/Representation.md

This example demonstrates a non-minified JSON structure, which should be avoided in API responses to save bandwidth.

```json
{
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "name": "offer-name",
  "seller": {
    "id": "5d8201b0...",
    "name": "user-name",
    "email": "user@allegrogroup.com"
  }
}
```

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

### Command Status Response - FAILED

Source: https://github.com/allegro/restapi-guideline/blob/master/docs/Command pattern.md

Example response indicating a command has failed. Includes input data, status, and an errors array.

```javascript
200 Ok
{
    "status" : "FAILED",
    "fromDate" : "2015-08-30T17:00:00.000Z",
    "duration" : "P7D",
    // other output data given to this command
    "errors" : [
        // errors description
    ]
}
```

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

### Synchronous Command Pattern Example

Source: https://github.com/allegro/restapi-guideline/blob/master/adr/ADR-002-public-endpoint-name-must-be-a-noun.md

Illustrates the Synchronous Command Pattern for executing custom operations that modify server state, using an HTTP POST method to a `-commands` suffixed endpoint.

```APIDOC
## POST /modify-offer-prices-commands

### Description
Endpoint to modify prices across multiple offers in a single API call.

### Method
POST

### Endpoint
/modify-offer-prices-commands

### Parameters
#### Request Body
- **changeType** (string) - Required - The type of price change (e.g., "INCREASE").
- **modificationValue** (number) - Required - The value of the modification.
- **modificationUnit** (string) - Required - The unit of modification (e.g., "PERCENTAGE").
- **includedOffers** (array) - Required - A list of offer IDs to modify.
  - (string) - Example: "12345"

### Request Example
```json
{
  "changeType": "INCREASE",
  "modificationValue": 15,
  "modificationUnit": "PERCENTAGE",
  "includedOffers": [
    "12345",
    "45678",
    "56789"
  ]
}
```

### Response
#### Success Response (200)
- **modifications** (array) - A list of performed modifications.
  - **offerId** (string) - The ID of the modified offer.
  - **previousPrice** (number) - The price before modification.
  - **newPrice** (number) - The price after modification.

#### Response Example
```json
{
  "modifications": [
    {
      "offerId": "12345",
      "previousPrice": 10,
      "newPrice": 11.5
    },
    {
      "offerId": "45678",
      "previousPrice": 4,
      "newPrice": 4.6
    },
    {
      "offerId": "56789",
      "previousPrice": 30,
      "newPrice": 34.5
    }
  ]
}
```
```

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

### GET Response for Asynchronous Command Status Check

Source: https://github.com/allegro/restapi-guideline/blob/master/adr/ADR-002-public-endpoint-name-must-be-a-noun.md

The response to a command status check includes the 'commandStatus' field, which can be 'DONE' or indicate that the operation is still in progress. It may also return the results of the operation, such as the modified offer prices in this example.

```json
{
  "commandStatus": "DONE",
  "modifications": [
    {
      "offerId": "12345",
      "previousPrice": 10,
      "newPrice": 11.5
    },
    {
      "offerId": "45678",
      "previousPrice": 4,
      "newPrice": 4.6
    },
    {
      "offerId": "56789",
      "previousPrice": 30,
      "newPrice": 34.5
    }
  ]
}
```

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

### Minified JSON Response Example

Source: https://github.com/allegro/restapi-guideline/blob/master/docs/Representation.md

API responses should be minified to reduce payload size. This example shows a compact JSON structure without unnecessary whitespace.

```json
{"id": "01234567-89ab-cdef-0123-456789abcdef","name":"offer-name","seller":{"id":"5d8201b0...",
"name":"user-name","email":"user@allegrogroup.com"}
}
```

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

### Collection as Root Element (Not Recommended)

Source: https://github.com/allegro/restapi-guideline/blob/master/docs/Representation.md

An example of a JSON response where a collection is the root element. This structure prevents the addition of metadata fields without breaking compatibility with existing clients.

```json
[
    {
        "id": "01234567-89ab-cdef-0123-456789abcdef",
        "name": "PINK FLOYD: THE ENDLESS RIVER"
    },
    {
        "id": "11234567-89ab-cdef-0123-456789abcdef",
        "name": "Ufomammut - Eve"
    }
]
```

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

### Get User

Source: https://github.com/allegro/restapi-guideline/blob/master/docs/Resource.md

Retrieves a specific user by their ID. The server returns an HTTP 200 Ok status code with the user's representation.

```APIDOC
## GET /users/{uuid}

### Description
Retrieves a specific user by their ID.

### Method
GET

### Endpoint
/users/{uuid}

### Parameters
#### Path Parameters
- **uuid** (string) - Required - The unique identifier of the user.

### Response
#### Success Response (200 Ok)
- **id** (string) - The unique identifier of the user.
- **firstName** (string) - The first name of the user.
- **middleName** (string) - The middle name of the user.
- **nickName** (string) - The nickname of the user.
- **email** (string) - The email address of the user.
- **createdAt** (string) - The timestamp when the user was created.
- **updatedAt** (string) - The timestamp when the user was last updated.

### Request Example
```bash
curl https://api.allegro.pl/users/{id} -H "Accept: application/vnd.allegro.public.v1+json"
```
```

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

### Synchronous Command Pattern Example: Modify Offer Prices

Source: https://github.com/allegro/restapi-guideline/blob/master/adr/ADR-002-public-endpoint-name-must-be-a-noun.md

Employ the Synchronous Command Pattern for custom operations that cannot be expressed by a noun and HTTP method. Use POST requests to endpoints ending in '-commands'. The request can optionally include an 'id' for idempotency.

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

```json
{
  "modifications": [
    {
      "offerId": "12345",
      "previousPrice": 10,
      "newPrice": 11.5
    },
    {
      "offerId": "45678",
      "previousPrice": 4,
      "newPrice": 4.6
    },
    {
      "offerId": "56789",
      "previousPrice": 30,
      "newPrice": 34.5
    }
  ]
}
```

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

### Retrieve Search Resource Data

Source: https://github.com/allegro/restapi-guideline/blob/master/docs/Representation.md

Use the search ID obtained from the creation response to retrieve the specific search data by making a GET request to the /product-searches/{search_id} endpoint.

```bash
curl -X GET https://api.allegro.pl/product-searches/4be770c3-4967-6805-8f13-0457dc8ed446 -H "Accept: application/vnd.allegro.public.v1+json"
```

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

### Collection Wrapped in Object with Metadata

Source: https://github.com/allegro/restapi-guideline/blob/master/docs/Representation.md

Example of a JSON response where a collection ('offers') is nested within a root object, allowing for additional metadata like 'count'. This structure supports future compatibility by not breaking existing clients when new fields are added.

```json
{
    "offers": [
        {
            "id": "01234567-89ab-cdef-0123-456789abcdef",
            "name": "PINK FLOYD: THE ENDLESS RIVER"
        },
        {
            "id": "11234567-89ab-cdef-0123-456789abcdef",
            "name": "Ufomammut - Eve"
        }
    ],
    "count": 4674
}
```

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

### Accept JSON in Request Bodies

Source: https://github.com/allegro/restapi-guideline/blob/master/README.md

Accept JSON as Content-Type data in PUT/PATCH/POST requests to create symmetry with JSON response bodies. This example shows a curl command for a POST request.

```bash
curl -X POST https://api.allegro.pl/users \
    -H "Content-Type: application/vnd.allegro.public.v1+json" \
    -d '{"name": "user-name"}'
```

```json
{
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "name": "user-name",
  "// ..."
}
```

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

### Checking Command Execution Status

Source: https://github.com/allegro/restapi-guideline/blob/master/docs/Command pattern.md

This snippet shows how to check the status of an asynchronously executed command. It uses a GET request to the command's specific URI.

```APIDOC
## GET /offers/{offerId}/{command-type}-commands/{UUID]

### Description
Retrieves the status and results of a previously submitted command.

### Method
GET

### Endpoint
/offers/{offerId}/{command-type}-commands/{UUID]

### Parameters
#### Path Parameters
- **offerId** (string) - Required - The ID of the offer associated with the command.
- **command-type** (string) - Required - The type of command.
- **UUID** (string) - Required - The UUID of the command.

### Response
#### Success Response (200 Ok)
- **status** (string) - The final status of the command execution (e.g., 'SUCCESSFUL', 'FAILED').
- **fromDate** (string) - The start date provided.
- **duration** (string) - The duration provided.
- **other output data** (object) - Other output data related to the command.
- **errors** (array) - Optional - An array of error descriptions if the command failed.

#### Response Example (Success)
```json
{
    "status" : "SUCCESSFUL",
    "fromDate" : "2015-08-30T17:00:00.000Z",
    "duration" : "P7D",
    // other output data given to this command
}
```

#### Response Example (Failure)
```json
{
    "status" : "FAILED",
    "fromDate" : "2015-08-30T17:00:00.000Z",
    "duration" : "P7D",
    // other output data given to this command
    "errors" : [
        // errors description
    ]
}
```
```

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

### Sample Product Data Structure

Source: https://github.com/allegro/restapi-guideline/blob/master/docs/Representation.md

This JSON structure represents a sample product with its details, including parameter groups and specific parameters with their values.

```json
{
    "products": [
        {
            "id": "7d3e4d5a-817c-45f8-930b-e319dbcedc5c",
            "name": "Doładowanie Heyah 5 zł",
            "parameterGroups": [
                {
                    "id": "4be770c3-6805-4967-8f13-0457dc8ed446",
                    "name": "Bazowe informacje",
                    "parameters": [
                        {
                            "id": "ce87a49d-55c3-476c-b7f8-349dfaf89510",
                            "name": "Rodzaj usługi",
                            "values": [
                                "Doładowanie"
                            ]
                        },
                        {
                            "id": "63baaaf2-534a-4c20-b1ed-e44952d7e556",
                            "name": "Nazwa",
                            "values": [
                                "Doładowanie Heyah 5 zł"
                            ]
                        },
                        {
                            "id": "ab98c5ec-f9c6-440f-9af0-a19caaba7eca",
                            "name": "Operator",
                            "values": [
                                "Heyah"
                            ]
                        },
                        {
                            "id": "7fdd3aa4-3cab-4d4f-93c4-9c2ff05bec86",
                            "name": "Wartość doładowania",
                            "values": [
                                "5 zł"
                            ]
                        }
                    ]
                }
            ]
        }
    ]
}
```

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

### Sample Custom User-Agent

Source: https://github.com/allegro/restapi-guideline/blob/master/docs/Resource.md

This is a sample of a custom User-Agent header for a mobile application, following the specified format.

```text
User-Agent: pl.allegro.sale/1.5.0 (Client-Id 01234567-89ab-cdef-0123-456789abcdef) Android/4.0 (Motorola XT1052)
```

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

### Create User with POST

Source: https://github.com/allegro/restapi-guideline/blob/master/docs/Resource.md

Use POST to create a new user. The request body must contain all entity properties. The server responds with HTTP 201 Created and includes a Location header and the full entity representation in the response body.

```bash
curl -X POST https://api.allegro.pl/users \
    -H "Accept: application/vnd.allegro.public.v1+json" \
    -H "Content-Type: application/vnd.allegro.public.v1+json" \
    -d
{
  "firstName": "John",
  "middleName": "Doe",
  "nickName": "Zen",
  "email": "zed@allegro.pl"
}
```

```json
{
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "firstName": "John",
  "middleName": "Doe",
  "nickName": "Zen",
  "email": "zed@allegro.pl",
  "createdAt": "2012-01-01T12:00:00.000Z",
  "updatedAt": "2012-01-01T13:00:00.000Z"
}
```

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

### Multi-level Sort by buyNow and createdAt

Source: https://github.com/allegro/restapi-guideline/blob/master/docs/Representation.md

Retrieves a list of offers sorted first by 'buyNow' in descending order, and then by 'createdAt' in ascending order for items with the same 'buyNow' price. This ensures older offers are listed first within identical price points.

```http
GET /offers?sort=-buyNow,createdAt
```

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

### API Versioning with Custom Media Types

Source: https://github.com/allegro/restapi-guideline/blob/master/docs/Resource.md

Specify API version using custom media types like `application/vnd.allegro.public.v1+json` in `Accept` or `Content-type` headers.

```http
Content-Type: application/vnd.allegro.public.v1+json
Accept: application/vnd.allegro.public.v1+json
```

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

### Get Search Data

Source: https://github.com/allegro/restapi-guideline/blob/master/docs/Representation.md

Retrieve the search data associated with a specific search ID by calling the 'new resource' endpoint.

```APIDOC
## GET /product-searches/{searchId}

### Description
Retrieves the search data for a given search ID.

### Method
GET

### Endpoint
/product-searches/{searchId}

### Parameters
#### Path Parameters
- **searchId** (string) - Required - The ID of the search to retrieve data for.

### Response
#### Success Response (200 OK)
- **[Search Data Structure]** - The detailed search data associated with the search ID.
```

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

### Custom User-Agent for a Service

Source: https://github.com/allegro/restapi-guideline/blob/master/docs/Resource.md

Use this format for a custom User-Agent header for a service. It includes service name, version, and host ID.

```text
User-Agent: Your-Service-Name/ServiceVersion (your-service-host-id) OSName
```

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

### Enum Value Representation in Java

Source: https://github.com/allegro/restapi-guideline/blob/master/docs/Representation.md

Enum values are represented as uppercase strings. This Java example shows a typical enum definition.

```java
public enum Color {
  WHITE,
  BLACK,
  RED,
  YELLOW,
  BLUE
}
```

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

### Access Offer Views via URL Context

Source: https://github.com/allegro/restapi-guideline/blob/master/README.md

Construct different URLs to access various views of an offer. Add context to the path to distinguish between different data sets, such as private seller data or public data.

```http
GET /sale/offers
```

```http
GET /offers
```

```http
GET /watched-offers
```

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

### Get Collection for Search ID

Source: https://github.com/allegro/restapi-guideline/blob/master/docs/Representation.md

Retrieve a collection of entities that match the criteria defined by a search ID by querying the base resource with the `search.id` parameter.

```APIDOC
## GET /products?search.id={searchId}

### Description
Retrieves a collection of products filtered by a specific search ID.

### Method
GET

### Endpoint
/products

### Parameters
#### Query Parameters
- **search.id** (string) - Required - The ID of the search to filter products by.
- **sort** (string) - Optional - Specifies the sorting order for the results.

### Response
#### Success Response (200 OK)
- **products** (array) - An array of product objects matching the search criteria.
  - **id** (string) - The unique identifier of the product.
  - **name** (string) - The name of the product.
  - **parameterGroups** (array) - An array of parameter groups for the product.
    - **id** (string) - The ID of the parameter group.
    - **name** (string) - The name of the parameter group.
    - **parameters** (array) - An array of parameters within the group.
      - **id** (string) - The ID of the parameter.
      - **name** (string) - The name of the parameter.
      - **values** (array) - An array of values for the parameter.
        - (string) - A specific value for the parameter.

### Request Example
```bash
curl -X GET https://api.allegro.pl/products?search.id=4be770c3-4967-6805-8f13-0457dc8ed446&sort=-parameterGroups.name -H "Accept: application/vnd.allegro.public.v1+json"
```
```

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

### Create Product Search Resource

Source: https://github.com/allegro/restapi-guideline/blob/master/docs/Representation.md

Submit a POST request to the /product-searches endpoint with detailed filtering criteria to create a new search resource. The response includes a search ID in the Location header upon successful creation (HTTP 201 Created).

```bash
curl -X POST https://api.allegro.pl/product-searches -H "Accept: application/vnd.allegro.public.v1+json" -d
{
    "limit": 100,
    "offset": 150,
    "parameterGroups": [
        {
            "id": "4be770c3-6805-4967-8f13-0457dc8ed446",
            "parameters": [
                {
                    "id": "ce87a49d-55c3-476c-b7f8-349dfaf89510",
                    "values": [
                        "Doładowanie"
                    ]
                },
                {
                    "id": "ab98c5ec-f9c6-440f-9af0-a19caaba7eca",
                    "values": [
                        "Heyah"
                    ]
                }
            ]
        }
    ]
}
```

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

### Set Beta Resource Headers

Source: https://github.com/allegro/restapi-guideline/blob/master/docs/Resource.md

Use these Content-Type and Accept headers when interacting with beta API resources. Beta resources may change and are not recommended for production use.

```http
Content-Type: application/vnd.allegro.beta.v1+json
Accept: application/vnd.allegro.beta.v1+json
```

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

### Enum Value Representation in JSON

Source: https://github.com/allegro/restapi-guideline/blob/master/docs/Representation.md

In JSON, enum values are represented as uppercase strings. This example shows how a color enum value would appear in a JSON object.

```javascript
{
  "color": "WHITE"
}
```

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

### Updating Offer Status with PATCH

Source: https://github.com/allegro/restapi-guideline/blob/master/docs/Command pattern.md

Shows how to update an offer's status using a PATCH request with JSON Patch operations. Similar to PUT, this can lead to complex, hidden business logic.

```bash
curl -X PATCH https://api.allegro.pl/offers/6546456 -H "Content-Type: application/vnd.allegro.public.v1+json" -d
[
    {
        "op" : "replace",
        "path" : "/status",
        "value" : "RENEWED"
    }
]
```

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

### Checking Command Execution Status

Source: https://github.com/allegro/restapi-guideline/blob/master/docs/Command pattern.md

Retrieves the status of an asynchronously executed command using a GET request on the command sub-resource. This allows for tracking the operation's progress.

```bash
curl -X GET https://api.allegro.pl/offers/6546456/renew-commands/23453425-34253245-3453454-345345 -H "Accept: application/vnd.allegro.public.v1+json"
```

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

### Consistent Paging with Offset and Limit

Source: https://github.com/allegro/restapi-guideline/blob/master/docs/Representation.md

Use offset and limit parameters for pagination. This provides more flexibility for clients compared to page and limit.

```http
GET /offers?offset=0&limit=100
```

```http
GET /offers?offset=100&limit=500
```

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

### Updating Offer Status with PUT

Source: https://github.com/allegro/restapi-guideline/blob/master/docs/Command pattern.md

Demonstrates updating an offer's status to 'RENEWED' using a PUT request. This approach is discouraged for complex operations due to potential hidden business logic.

```bash
curl -X PUT https://api.allegro.pl/offers/6546456 -H "Content-Type: application/vnd.allegro.public.v1+json" -d
{
    "status" : "RENEWED",
    // all other offer fields ...
}
```

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

### Accept JSON in POST Request Body

Source: https://github.com/allegro/restapi-guideline/blob/master/docs/Representation.md

Accept JSON as Content-Type data in POST request bodies for symmetry with JSON response bodies. This example uses curl to send a JSON payload.

```bash
curl -X POST https://api.allegro.pl/users \
    -H "Content-Type: application/vnd.allegro.public.v1+json" \
    -d '{"name": "user-name"}'
```

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

### Adding a Command with PUT

Source: https://github.com/allegro/restapi-guideline/blob/master/docs/Command pattern.md

Implements the command pattern by adding a command to a resource's command sub-resource using PUT with a client-generated UUID. This ensures idempotency for complex operations.

```bash
curl -X PUT https://api.allegro.pl/offers/6546456/renew-commands/23453425-34253245-3453454-345345 -H "Content-Type: application/vnd.allegro.public.v1+json" -d
{
    "fromDate" : "2015-08-30T17:00:00.000Z",
    "duration" : "P7D",
    // other input data for this command
}
```

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

### Filtering with Query Parameters

Source: https://github.com/allegro/restapi-guideline/blob/master/README.md

Demonstrates how to use query parameters for filtering API resources. Supports simple field filtering, nested field filtering using dot notation, range filtering with suffixes (gt, lt, gte, lte), and filtering by multiple values in a single field.

```APIDOC
## Filtering

### Simple filters in query string

Use a query parameter for each field that supports filtering. For example, to filter general deliveries by name and city:

```bash
curl -X GET https://api.allegro.pl/general-deliveries?name=UP+Poznań+41&address.city=Poznań -H "Accept: application/vnd.allegro.public.v1+json"
```

Rules for query string filters:
* Refer directly to collection entities (e.g., `name`).
* Use "." (dot) for nested fields (e.g., `address.city`).

### Range Filtering

To support ranges, use virtual fields with suffixes:
- **gt**: greater than
- **lt**: less than
- **gte**: greater or equal
- **lte**: less or equal

Example request for rate greater than 200:

````bash
curl -X GET https://api.allegro.pl/general-deliveries?rate.gt=200 -H "Accept: application/vnd.allegro.public.v1+json"
````

### Filter by multiple values in one field

To filter by multiple values in a single field, repeat the field name with different values:

```bash
curl -X GET https://api.allegro.pl/general-deliveries?shipments.payments=PRE&shipments.payments=POST -H "Accept: application/vnd.allegro.public.v1+json"
```
```

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

### Plural Names for Array Properties

Source: https://github.com/allegro/restapi-guideline/blob/master/docs/Representation.md

Array types should use plural property names, while other property names should be singular. For example, use `offers` for an array of offers and `user` for a single user ID.

```javascript
{
  // Singular
  "user": "123456",
  // An array of siblings, plural
  "offers": [{},{}],
  // "totalItem" doesn't sound right
  "totalCount": 10,
  // But maybe "offersCount" or just "count" is better
  "offersCount": 10,
}
```

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

### Lowercase and Dash-Separated Paths

Source: https://github.com/allegro/restapi-guideline/blob/master/docs/Resource.md

Use lowercase and dash-separated names for resource paths for consistency.

```text
/general-deliveries
/application-configurations
```

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

### Resource Naming Convention

Source: https://github.com/allegro/restapi-guideline/blob/master/docs/Resource.md

Use plural names for resource collections to maintain consistency.

```text
/users
/offers
/contests
/shipments
/transactions
/payments
```

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

### Custom User-Agent for Mobile Application

Source: https://github.com/allegro/restapi-guideline/blob/master/docs/Resource.md

Use this format for a custom User-Agent header for a mobile application. It includes application details, client ID, and OS information.

```text
User-Agent: Application-Package-Name_BundleId/ApplicationVersion (Client-Id CMDeviceUUID) OSName/OSVersion (Manufacturer Model)
```

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

### Access Public Offer Data

Source: https://github.com/allegro/restapi-guideline/blob/master/docs/Resource.md

Use the base '/offers' path to retrieve publicly available offer data.

```http
GET /offers
```

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

### Update User with PUT

Source: https://github.com/allegro/restapi-guideline/blob/master/docs/Resource.md

Use PUT to update an existing user. Provide all updatable properties in the request body. The server responds with HTTP 200 Ok and the updated entity representation.

```bash
curl -X PUT https://api.allegro.pl/users/01234567-89ab-cdef-0123-456789abcdef \
    -H "Accept: application/vnd.allegro.public.v1+json" \
    -H "Content-Type: application/vnd.allegro.public.v1+json" \
    -d
{
  "middleName": null,
  "nickName": "Zed"
}
```

```json
{
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "firstName": "John",
  "middleName": null,
  "nickName": "Zed",
  "email": "zed@allegro.pl",
  "createdAt": "2012-01-01T12:00:00.000Z",
  "updatedAt": "2012-01-01T13:00:00.000Z"
}
```

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

### Validate Specific Fields with Dry Run

Source: https://github.com/allegro/restapi-guideline/blob/master/docs/Resource.md

To validate only specific fields, use the `include` query parameter multiple times, e.g., `include=login&include=password`.

```bash
curl -X POST https://api.allegro.pl/users?dryRun=true&include=login&include=password  \
    -d {"login": "userLogin", "password": "userPassword", "email": "user@allegro.pl"}
    -H "Content-type: application/vnd.allegro.public.v1+json"
    -H "Accept: application/vnd.allegro.public.v1+json"
```

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

### Create User

Source: https://github.com/allegro/restapi-guideline/blob/master/docs/Resource.md

Creates a new user. The server requires all entity properties in the request body and returns an HTTP 201 Created status code with the new entity representation in the response body.

```APIDOC
## POST /users

### Description
Creates a new user.

### Method
POST

### Endpoint
/users

### Request Body
- **firstName** (string) - Required - The first name of the user.
- **middleName** (string) - Optional - The middle name of the user.
- **nickName** (string) - Required - The nickname of the user.
- **email** (string) - Required - The email address of the user.

### Request Example
```bash
curl -X POST https://api.allegro.pl/users \
    -H "Accept: application/vnd.allegro.public.v1+json" \
    -H "Content-Type: application/vnd.allegro.public.v1+json" \
    -d
{
  "firstName": "John",
  "middleName": "Doe",
  "nickName": "Zen",
  "email": "zed@allegro.pl"
}
```

### Response
#### Success Response (201 Created)
- **id** (string) - The unique identifier of the created user.
- **firstName** (string) - The first name of the user.
- **middleName** (string) - The middle name of the user.
- **nickName** (string) - The nickname of the user.
- **email** (string) - The email address of the user.
- **createdAt** (string) - The timestamp when the user was created.
- **updatedAt** (string) - The timestamp when the user was last updated.

#### Response Example
```json
{
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "firstName": "John",
  "middleName": "Doe",
  "nickName": "Zen",
  "email": "zed@allegro.pl",
  "createdAt": "2012-01-01T12:00:00.000Z",
  "updatedAt": "2012-01-01T12:00:00.000Z"
}
```
```

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

### Delete User with DELETE

Source: https://github.com/allegro/restapi-guideline/blob/master/docs/Resource.md

Use DELETE to remove a user. The server responds with HTTP 204 No Content and an empty response body. The Accept header is generally not required for this method.

```bash
curl -X DELETE https://api.allegro.pl/users/{id}
```

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

### Set Accept-Language Header for Localization

Source: https://github.com/allegro/restapi-guideline/blob/master/README.md

Clients should set the `Accept-Language` header to request localized user messages. Supported formats include wildcard matching (e.g., 'en-*') and specific tags (e.g., 'pl-PL').

```http
Accept-Language: en-* (* is any valid type eg. "GB", "US")
```

```http
Accept-Language: pl-PL
```

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

### Descending Sort by buyNow

Source: https://github.com/allegro/restapi-guideline/blob/master/docs/Representation.md

Retrieves a list of offers sorted in descending order by the 'buyNow' price. This is useful for prioritizing higher-priced items.

```http
GET /offers?sort=-buyNow
```

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

### Access User's Watched Offers

Source: https://github.com/allegro/restapi-guideline/blob/master/docs/Resource.md

To retrieve a list of offers that a user is watching, use the '/watched-offers' path.

```http
GET /watched-offers
```

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

### Sample Response for Filtered General Deliveries

Source: https://github.com/allegro/restapi-guideline/blob/master/docs/Representation.md

This is a sample JSON response structure for a filtered list of general delivery points.

```json
{
  "points": [
    {
      "id": "de305d54-75b4-431b-adb2-eb6b9e546014",
      "name": "UP Poznań 41",
      "address": {
        "street": "Ulica Starołęcka 42",
        "code": "61-360",
        "city": "Poznań"
      }
    }
  ]
}
```

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

### Description Object Structure

Source: https://github.com/allegro/restapi-guideline/blob/master/docs/Glossary.md

Defines the structure for a description, differentiating between a brief summary and full text. Use 'description' for the main object.

```json
{
    "description": {
        "summary": "",
        "text": ""
    }
}
```

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

### List Users

Source: https://github.com/allegro/restapi-guideline/blob/master/docs/Resource.md

Retrieves a list of users. The server returns an HTTP 200 Ok status code with the collection of users presented as an array.

```APIDOC
## GET /users

### Description
Retrieves a list of users.

### Method
GET

### Endpoint
/users

### Response
#### Success Response (200 Ok)
- **users** (array) - An array of user objects.

### Request Example
```bash
curl https://api.allegro.pl/users -H "Accept: application/vnd.allegro.public.v1+json"
```
```

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

### Access Private Offer Data

Source: https://github.com/allegro/restapi-guideline/blob/master/docs/Resource.md

To retrieve offer data that is only available to the seller, include '/sale/' in the URL path.

```http
GET /sale/offers
```

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

### Adding a Command

Source: https://github.com/allegro/restapi-guideline/blob/master/docs/Command pattern.md

This snippet demonstrates how to add a complex operation command to a business resource. It uses the PUT method with a client-generated UUID in the URI to ensure idempotency. The request body contains the necessary input data for the command.

```APIDOC
## PUT /offers/{offerId}/{command-type}-commands/{UUID]

### Description
Adds a command to execute a complex operation on a specific resource. The operation is executed asynchronously.

### Method
PUT

### Endpoint
/offers/{offerId}/{command-type}-commands/{UUID]

### Parameters
#### Path Parameters
- **offerId** (string) - Required - The ID of the offer to perform the command on.
- **command-type** (string) - Required - The type of command to execute (e.g., 'renew').
- **UUID** (string) - Required - A client-generated UUID for idempotency.

#### Request Body
- **fromDate** (string) - Required - The start date for the operation.
- **duration** (string) - Required - The duration for the operation (e.g., 'P7D').
- **other input data** (object) - Optional - Additional input data required for the command.

### Request Example
```bash
curl -X PUT https://api.allegro.pl/offers/6546456/renew-commands/23453425-34253245-3453454-345345 -H "Content-Type: application/vnd.allegro.public.v1+json" -d
{
    "fromDate" : "2015-08-30T17:00:00.000Z",
    "duration" : "P7D",
    // other input data for this command
}
```

### Response
#### Success Response (201 Created)
- **status** (string) - The initial status of the command execution (e.g., 'RUNNING').
- **fromDate** (string) - The start date provided.
- **duration** (string) - The duration provided.
- **other output data** (object) - Other output data related to the command.

#### Response Example
```json
{
    "status" : "RUNNING",
    "fromDate" : "2015-08-30T17:00:00.000Z",
    "duration" : "P7D",
    // other output data given to this command
}
```
```

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

### Price and Currency Structure

Source: https://github.com/allegro/restapi-guideline/blob/master/docs/Representation.md

Prices are represented as a structure with 'amount' and 'currency' fields. Ensure the amount is a string with a dot as the decimal separator and at most two decimal places.

```javascript
{
    "buyNow": {
        "amount": "11.25",
        "currency": "PLN"
    }
}
```

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

### Use UUIDs for Resource IDs

Source: https://github.com/allegro/restapi-guideline/blob/master/docs/Representation.md

Assign a unique `id` attribute to each resource, preferably using UUIDs in a lowercase `8-4-4-4-12` format. Avoid auto-incrementing IDs.

```javascript
"id": "01234567-89ab-cdef-0123-456789abcdef"
```

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

### POST Request for Asynchronous Command Trigger

Source: https://github.com/allegro/restapi-guideline/blob/master/adr/ADR-002-public-endpoint-name-must-be-a-noun.md

This JSON payload is sent to trigger an asynchronous command, such as modifying offer prices. It includes an array of modifications, each specifying an offer ID and price changes. The request itself does not have a fixed structure but may include an 'id' for idempotency.

```json
{
  "modifications": [
    {
      "offerId": "12345",
      "previousPrice": 10,
      "newPrice": 11.5
    },
    {
      "offerId": "45678",
      "previousPrice": 4,
      "newPrice": 4.6
    },
    {
      "offerId": "56789",
      "previousPrice": 30,
      "newPrice": 34.5
    }
  ]
}
```

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

### Filter Product Collection by Search ID

Source: https://github.com/allegro/restapi-guideline/blob/master/docs/Representation.md

Retrieve a filtered collection of products by appending the 'search.id' query parameter to the base resource endpoint (e.g., /products). Sorting can also be applied using the 'sort' parameter.

```bash
curl -X GET https://api.allegro.pl/products?search.id=4be770c3-4967-6805-8f13-0457dc8ed446&sort=-parameterGroups.name -H "Accept: application/vnd.allegro.public.v1+json"
```

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

### Minimize Resource Nesting

Source: https://github.com/allegro/restapi-guideline/blob/master/docs/Resource.md

Limit resource nesting depth by preferring root paths and using nesting only for scoped collections.

```javascript
/users/{userId}/offers/{offerId}/shipments/{shipmentId}
```

```javascript
/users/{userId}
/users/{userId}/offers
/offers/{offerId}
/offers/{offerId}/shipments
/shipments/{shipmentId}
```

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

### Perform Dry Run Validation of User Creation Request

Source: https://github.com/allegro/restapi-guideline/blob/master/README.md

Use the `dryRun=true` query parameter to validate all parameters of a user creation request without persisting the data. This is useful for frontend validation.

```bash
curl -X POST https://api.allegro.pl/users?dryRun=true  \
    -d {"login": "userLogin", "password": "userPassword", "email": "user@allegro.pl"}
    -H "Content-type: application/vnd.allegro.public.v1+json" \
    -H "Accept: application/vnd.allegro.public.v1+json"
```

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

### Image Object Structure

Source: https://github.com/allegro/restapi-guideline/blob/master/docs/Glossary.md

Represents the structure for an image object, including its URL and title. Use 'image' instead of 'picture'.

```json
{
    "image": {
        "url": "",
        "title": ""
    }
}
```

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

### Validate Specific Fields in User Creation Request

Source: https://github.com/allegro/restapi-guideline/blob/master/README.md

To validate only specific fields like 'login' and 'password', append `include=fieldName` parameters to the `dryRun` request. This allows for targeted validation.

```bash
curl -X POST https://api.allegro.pl/users?dryRun=true&include=login&include=password  \
    -d {"login": "userLogin", "password": "userPassword", "email": "user@allegro.pl"} \
    -H "Content-type: application/vnd.allegro.public.v1+json" \
    -H "Accept: application/vnd.allegro.public.v1+json"
```

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

### Using RFC 1766 for Language Tags

Source: https://github.com/allegro/restapi-guideline/blob/master/docs/Representation.md

Refer to languages using RFC 1766 language tags, which combine country and language codes.

```json
{
    "user" : {
        // ...
        "prefferedLanguage": "en-GB" //  form of English in the UK, but also countries such as Canada
    }
}
```