# What conventions does the API use?

#### Attribute Conventions

- Keys generally match the attribute name on their respective models.
- **Exception:** Attributes ending in "\_code" should omit the suffix when passed to the API, e.g. `currency_code` => `currency`

#### Relationship Conventions

- Nested data should use a **snake\_case** version of the relationship method name where present, e.g.: `shippingMethod` => `shipping_method`

#### Price Conventions

- Prices retrieved from the API are mostly in the currency's smallest unit, e.g. `1000` = `10 GBP`
- Prices should generally be provided in the currency’s standard unit, e.g. `10` = `10 GBP` (unless otherwise stated)
- Prices should generally be passed as an object, e.g.:  
      
    ```
    {
        "price": {
            "amount": 400, // Excluding tax
            "tax": 80
        }
    }
    ```
    
    **Exception:** Some endpoints support passing a single tax-inclusive value:
    
    ```
    {
        "price": 480 // Including tax
    }
    ```
    
    See the relevant endpoint docs to see if this is supported for an endpoint

#### Date Conventions

- Dates must be **Carbon-parseable**, supported formats include: 
    - 2023-09-01T09:29:41.000000Z
    - 2023-09-01 09:29:41
    - 2023-09-01 (defaults to midnight if no time is provided)

#### Pagination Conventions

<table border="1" id="bkmrk-parameter-descriptio" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 33.3731%;"></col><col style="width: 33.3731%;"></col><col style="width: 33.3731%;"></col></colgroup><tbody><tr><td>**Parameter**  
</td><td>**Description**  
</td><td>**Example**  
</td></tr><tr><td>`page`</td><td>The page number (default: 1)</td><td>`?page=2`</td></tr><tr><td>`per_page`</td><td>The number of results per page (default: 24, max: 96)</td><td>`?per_page=48`</td></tr><tr><td>`ids`</td><td>Comma-separated list of IDs to fetch</td><td>`?ids=1,2,5`</td></tr><tr><td>`min_updated_at`</td><td>The min updated at for a product</td><td>`?min_updated_at=2023-08-30%2010:35:05`</td></tr><tr><td>`max_updated_at`</td><td>The max updated at for a product</td><td>`?max_updated_at=2023-08-30%2010:35:05`</td></tr></tbody></table>

<p class="callout info">The `min_updated_at` and `max_updated_at` parameters are only supported by index endpoints.</p>

Responses follow Laravel's pagination format, e.g.:

```
{
    "current_page": 1,
    "data": [
        //...
    ],
    "first_page_url": "http://aero.test/api/products?page=1",
    "from": 1,
    "last_page": 2,
    "last_page_url": "http://aero.test/api/products?page=2",
    "next_page_url": "http://aero.test/api/products?page=2",
    "path": "http://aero.test/api/products",
    "per_page": 24,
    "prev_page_url": null,
    "to": 24,
    "total": 29
}
```

#### Scope Conventions

- Index endpoints support a scope parameter, which is a comma-separated list of scopes.
- Supported scopes are endpoint-specific and documented in endpoint-specific example docs.

#### Image Factory Conventions

<table border="1" id="bkmrk-parameter-descriptio-1" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 33.3731%;"></col><col style="width: 33.3731%;"></col><col style="width: 33.3731%;"></col></colgroup><tbody><tr><td>**Parameter**  
</td><td>**Description**  
</td><td>**Example**  
</td></tr><tr><td>`image_factory_width`</td><td>Output image width</td><td>`?image_factory_width=200`</td></tr><tr><td>`image_factory_height`</td><td>Output image height</td><td>`?image_factory_height=200`</td></tr><tr><td>`image_factory_options`</td><td>Comma-seperated options</td><td>`?image_factory_options=flip,greyscale`</td></tr></tbody></table>

<p class="callout info">If any of these query parameters are present in the GET requests, Image Factory will be applied.</p>