In the continuous evolution of our SaaS solution, we perform a review/update of our API every six months. This review results in some endpoints, attributes, or operations being deprecated/removed.

The deprecations for API v4 and API v5 endpoints are announced six months in advance of their removal date to give you time to verify that you're not impacted by them or to migrate your code accordingly.

🚧
Announcements and deprecations take place around October 15th and April 15th every year.

October 15,2021 > April 15,2022

❗️
Deprecation Date: 15 October 2021
Removal Date: 15 April 2022

API_1 (v4) API (v5)

GET

API Endpoint Notes

/api_1.php/catalog-views

An attribute in the response payload has been replaced:

Deprecated Attribute: type

Replacement Attribute: code

{
    "success": true,
    "total": 1,
    "rows": [
        {
            "id": 1,
            "name": "E-Commerce",
            "type": "ECO", // Deprecated and will be removed
            "code": "ECO", // Should be used instead
            "description": null,
            "fields": [],
            "catalogXObjectTypes": [],
            "objectType": "document"
        }
    ]
}

/api_1.php/catalog-views/INTERNAL-ID

An attribute in the response payload has been replaced:

Deprecated Attribute: type

Replacement Attribute: code

{
    "success": true,
    "data": {
        "id": 1,
        "name": "E-Commerce",
        "type": "ECO", // Deprecated and will be removed
        "code": "ECO", // Should be used instead
        "description": null,
        "origin_catalog_view_id": null,
        "fields": []
    }
}

CRUD

API Endpoint	Notes
`/api_1.php/profiles/picture/:id/:width/:height`	All HTTP methods are deprecated for this particular endpoint. Replacement(s)*: `/api/users`
`/api_1.php/users`	All HTTP methods are deprecated for this particular endpoint. Replacement(s)*: `/api/users`
`/api_1.php/users/groups`	All HTTP methods are deprecated for this particular endpoint. Replacement(s)*: `/api/users`
`/api_1.php/users/groups`	All HTTP methods are deprecated for this particular endpoint. Replacement(s)*: `/api/users/groups`
`/api_1.php/users/INTERNAL-ID`	All HTTP methods are deprecated for this particular endpoint. Replacement(s)*: `/api/users`
`/api_1.php/users/me`	All HTTP methods are deprecated for this particular endpoint. Replacement(s)*: `/api/users`
`/api_1.php/users/me/uploadProfilePhoto`	All HTTP methods are deprecated for this particular endpoint. Replacement(s)*: `/api/users`
`/api_1.php/users/permissions`	All HTTP methods are deprecated for this particular endpoint. Replacement(s)*: `/api/users`
`/api_1.php/users/validate`	All HTTP methods are deprecated for this particular endpoint. Replacement(s)*: `/api/users`
`/api_1.php/users-and-groups`	All HTTP methods are deprecated for this particular endpoint. Replacement(s)*: `/api/users`
`/api_1.php/user-settings`	All HTTP methods are deprecated for this particular endpoint. Replacement(s)*: `/api/users`
`/api_1.php/xobject_types`	All HTTP methods are deprecated for this particular endpoint. Replacement(s)*: `/api/link-types`
`/api_1.php/xobject_types/INTERNAL-ID`	All HTTP methods are deprecated for this particular endpoint. Replacement(s): `/api/link-types/CODE`

CRUD

API Endpoint	Notes
`/api/assets/CODE`	In the response payload, the `attributes.code` attribute is deprecated. attributes_ is an array of: `id` `code` <- deprecated item `values`
`/api/catalogs/CODE`	In the response payload, the `attributes.code` attribute is deprecated. attributes_ is an array of: `id` `code` <- deprecated item `values`
`/api/documents/CODE`	In the response payload, the `attributes.code` attribute is deprecated. attributes_ is an array of: `id` `code` <- deprecated item `values`
`/api/variants/CODE`	In the response payload, the `attributes.code` attribute is deprecated. attributes_ is an array of: `id` `code` <- deprecated item `values`
`/api/catalogs/CODE/classifications`	In the response payload, the `fieldData` attribute is deprecated.
`/api/data-flow-profiles/models`	All HTTP methods are deprecated for this particular endpoint. Replacement(s) `/api/import/models` `/api/export/models`
`/api/link-types`	In the response payload, the `parent` and `child` attributes are deprecated. Replacement(s) `parent` -> `origin` `child` -> `target`

April 29, 2022 > October 15, 2022

❗️
Deprecation Date: April 29, 2022
Removal Date: October 15, 2022

API-v5 - POST /api/completenesses/settings && GET /api/enums/colors - The color attribute will accept only hexadecimal color

Currently: accept both color name and hexadecimal value
Future: accept only hexadecimal in uppercase format

This is a POST that will be ok for /api/completenesses/settings :

{
  "color": "#4DABF7",
  "fields": [],
  "attributes": [],
  "linkTypes": [],
  "id": "identifier_example",
  "documentTypeCode": "document_type_example",
  "description": {},
  "name": {}
}

This is a POST that will be considered as a bad request for /api/completenesses/settings :

{
  "color": "blue",
  "fields": [],
  "attributes": [],
  "linkTypes": [],
  "id": "identifier_example",
  "documentTypeCode": "document_type_example",
  "description": {},
  "name": {}
}

API-v5 - limit parameter while retrieving data : maximum accepted value is set to 50 (100 on current version)

Here are the endpoints impacted by this change :

GET /api/documents
GET /api/assets
GET /api/variants
GET /api/classifications
GET /api/links

Let's say a script calls the endpoint GET /api/documents with a limit of 70, the API will return the first 50 documents.
In concrete terms:

If you use the path links provided in the response bodies, these will clearly indicate 50 and not 70. So your script will not be impacted
If you don't use the path links provided in the response bodies but your script queries page 2 on its own with a limit of 70, you will have an offset of 20 documents not returned. In this case, we invite you to change the value of this limit in your scripts.

October 17, 2022 > May 16, 2023

❗️
Deprecation Date: October 17, 2022
Removal Date: May 16, 2022

Rate Limiting

Medias (binaries & thumbnails)

Currently: 3 consecutive calls from the same IP on the same URL that returns a 4xx or 5xx : 429 for one hour. Automatic renewal (offset) with each new call.
Future: No changes will be made

API

Currently: not more than 15 calls/s
Future:
6K calls per 10 minutes bucket : If exceeded, 429 HTTP response code will be returned (10 minute bucket)
300K calls per day (fair use) : If exceeded, 429 HTTP response code will be returned (1 day bucket)

Variant export from the Document page > Variant's tab

Currently: inactive variants associated with the current document are exported
Future: inactive variants associated with the current document are not exported anymore

Search : Tag & workflow filters

Currently: There are 3 ways to filter on tags + workflow steps
The first one is the Legacy filter which include both tags & workflow steps
A specific filter for Tags has been added a few weeks ago
A specific filter foreach Workflow has been added a few weeks ago
Future: the legacy filter will be removed. A conversion for this Legacy filter to the Tags or Workflow filter will be done by Quable

May, 2022 > October 15, 2023

❗️
Deprecation Date: May, 2022
Removal Date: October 15, 2022

API v5

Filters

Currently: the API v5 accepts "=" filter

GET /api/documents?attributes.string_type_attribute=value1  
GET /api/documents?attributes.string_type_attribute[]=value1

Future: "equals" filter is now available and an automatic convert is done

GET /documents?attributes.string_type_attribute[equals]=value1

Sub-resources limitation on documents

When you retrieve documents via the API, Quable returns the full set of sub-resources.
In some cases, the collection of sub-resources may contain thousands of items. This causes performance issues for the API but also for processing.
If this happens, it is good practice to request the sub-resources via another call.
We will therefore limit the number of sub-resources in a collection to 100 elements.

/api/completenesses and attribute.attributeSet

attributeSet will be removed from attributes key (GET, POST, PUT, DELETE)

CDN URL and asset code

Currently: URLs are defined this way : https://cdn.quable.com/{instance}/{asset_code}/{image_profile}/...
Future: URLs will be defined this way : https://cdn.quable.com/{instance}/{random_identifier}/{image_profile}/...

There is an impact if you do have script or process that build the URL, based on asset code (i.e. without using the URL given by export or API)