!!!danger
Deprecation Date: April, 2026
Removal Date: October 15, 2026
!!!

## Removal of field `documentTypeCode` in favor of `documentType.id`

The `documentTypeCode` field has been removed. It was superseded by the `documentType.id` field, which carries the same value within the existing `documentType` object.

The motivation behind this change was to standardize our APIs.

### Impacted endpoints

- `GET /api/attributes`
- `POST /api/attributes`
- `GET /api/attributes/:id`
- `PUT /api/attributes/:id`
- `GET /api/attributes-sets`
- `POST /api/attributes-sets`
- `GET /api/attributes-sets/:id`
- `PUT /api/attributes-sets/:id`
- `GET /api/completeness-settings`
- `POST /api/completeness-settings`
- `GET /api/completeness-settings/:id`
- `PUT /api/completeness-settings/:id`

### Migration guide

- **Previously:** the API response contained both fields:

```json
curl --request GET 'https://{{instance}}.quable.com/api/attributes/{id}'

{
  "documentTypeCode": "quable_article",
  "documentType": {
    "id": "quable_article"
  }
}
```

- **Now:** the `documentTypeCode` field is no longer present. Use `documentType.id` instead.

## Changes in `application/json` format for several endpoints

Inconsistencies were detected on 3 API endpoints when using the `application/json` format. The response included additional keys that served no purpose and made those responses non-standard compared to other endpoints.

The motivation behind this change was to standardize our APIs.

### Impacted endpoints

- `GET /api/documents`
- `GET /api/variants`
- `GET /api/assets`

### Migration guide

- **Previously:** the response was a JSON object keyed by `legacyId`:

```json
curl --request GET 'https://{{instance}}.quable.com/api/documents'
--header 'Content-Type: application/json'

{
  "42": {
    "@id": "/documents/alice",
    "id": "alice",
    "legacyId": "42",
    "attributes": { ... }
  }
}
```

- **Now:** the response is a JSON array:

```json
curl --request GET 'https://{{instance}}.quable.com/api/documents'
--header 'Content-Type: application/json'

[
  {
    "@id": "/documents/alice",
    "id": "alice",
    "legacyId": "42",
    "attributes": { ... }
  }
]
```

During the deprecation period, the new format could be previewed by adding the `X-Quable-Deprecation: oct-26` header to requests. This header no longer has any effect.

## Removal of `application/hal+json` format for content negotiation

The `application/hal+json` content type has been removed in favor of `application/ld+json`. Both formats were redundant and we want to focus on formats that are well supported by our team.

- If you do **not** provide an `Accept` header, the default content type remains `application/ld+json` — no action needed.
- If you used `Accept: application/hal+json`, you must migrate to `Accept: application/ld+json`. The data structure differs, so code adaptation is required.

### Migration guide

- **Previously:**

```bash
curl --request GET "https://{{instance}}.quable.com/api/documents?page=1&limit=2" \
--header 'Accept: application/hal+json'

{
    "_links": {
        "self": { "href": "/api/documents?limit=2&page=1" },
        "first": { "href": "/api/documents?limit=2&page=1" },
        "last": { "href": "/api/documents?limit=2&page=35" },
        "next": { "href": "/api/documents?limit=2&page=2" },
        "item": [
            { "href": "/api/documents/0123456789" },
            { "href": "/api/documents/020714858735" }
        ]
    },
    "totalItems": 70,
    "itemsPerPage": 2,
    "_embedded": {
        "item": [ { ... } ]
    }
}
```

- **Now:**

```bash
curl --request GET "https://{{instance}}.quable.com/api/documents?page=1&limit=2" \
--header 'Accept: application/ld+json'

{
    "@context": "/api/contexts/Document",
    "@id": "/api/documents",
    "@type": "hydra:Collection",
    "hydra:totalItems": 70,
    "hydra:member": [ { ... } ],
    "hydra:view": {
        "@id": "/api/documents?limit=2&page=1",
        "@type": "hydra:PartialCollectionView",
        "hydra:first": "/api/documents?limit=2&page=1",
        "hydra:last": "/api/documents?limit=2&page=35",
        "hydra:next": "/api/documents?limit=2&page=2"
    },
    "hydra:search": { ... }
}
```

## Removal of sign-in with credentials in query string

To reinforce security, credentials are no longer accepted as query string parameters on `POST /api_1.php/sessions`.

### Migration guide

- **Previously:**

```bash
curl --request POST "https://{{instance}}.quable.com/api_1.php/sessions?signin[username]=my-username&signin[password]=my-password"
```

- **Now:** credentials must be provided as `form/data` or `application/json`:

```bash
curl --request POST 'https://{{instance}}.quable.com/api_1.php/sessions' \
--form 'signin[username]="my-username"' \
--form 'signin[password]="mypassword"'

# or

curl --request POST 'https://{{instance}}.quable.com/api_1.php/sessions' \
--header 'Content-Type: application/json' \
--data-raw '{
    "signin": {
        "username": "my-username",
        "password": "my-password"
    }
}'
```