Squidex 3.0: API Compatibility

API Compatibility

The API for Squidex 3.0 contains a lot of changes to 2.0. This document describes the main differences.

The good news first! There is no change in the endpoints to retrieve content or assets, including the GraphQL endpoint.

Motivation

These changes are driven by two requirements:

1. POST and PUT endpoints must return the full entity (e.g. the schema object) so that the UI does not have to consider how the entity will be structured after an update.

2. Implement HATEOAS (Hypermedia as the Engine of Application State) to tell the client which operations are possible for a given entity and how to invoke them.

Given the list of Apps as an example, our JSON response has the following format now:

{
   "items": [{
       "id": 1,
       "name": "my-app",
       "_links": {
          "delete": { "method": "DELETE", "href": "/api/apps/1" }
       }
    }],
    "_links": {
        "create": { "method": "POST", "href": "/api/apps" }
     }
}

This format will be called Items-Object from now.

A single App in 3.0 has the following format:

{
    "id": 1,
    "name": "my-app",
    "_links": {
        "delete": { "method": "DELETE", "href": "/api/apps/1" }
    }
}

If Squidex 2.0 and a lower list of Apps was returned as a JSON array, it will not be possible to add the links to create the endpoint.

[{
    "id": 1,
    "name": "my-app",
    "_links": {
        "delete": { "method": "DELETE", "href": "/api/apps/1" }
    }
}]

General Changes

1. HATEOAS

As described above, each entity or list of entities will now contain a _links object, with all possible operations. If the operation is not possible or the current user does not have the correct permission, the link will not be present.

RISK to break something: LOW

2. Metadata

Data that is not part of the entity but must be returned as a result of the operation is added to a _meta object.

Example: When uploading an asset, the API checks if the same asset has already been uploaded. If this is the case, the response will contain the uploaded asset with additional information if the asset was already part of the App:

{
    "id": 1,
    "fileName": "Logo.jpeg",
    "fileSize": 1024,
    "_links": {
        "delete": { "method": "DELETE", "href": "/api/assets/1" }
    },
    "_meta": {
        "isDuplicate": "1"
    }
}

RISK to break something: LOW

3. Full Response Objects

All POST and PUT endpoints now return the full entity (e.g. the schema object). This is not a breaking change for you if your client displays the following behaviour:

1. The client does not break when the JSON response contains additional properties.

2. The client does not break when an endpoint that has previously returned a 204 No Content status code now returns 200 OK now (usually the case).

3. The client does not break when an endpoint that has not returned a JSON response before, now returns a response.

RISK to break something: MEDIUM

Specific Changes

Contents

The following endpoints have been removed to prepare for the coming workflow system:

• PUT /api/content/{app}/{name}/{id}/archive/

• PUT /api/content/{app}/{name}/{id}/publish/

• PUT /api/content/{app}/{name}/{id}/restore/

• PUT /api/content/{app}/{name}/{id}/unpublish/

The replacement is a generalized status endpoint:

PUT /api/content/{app}/{name}/{id}/status/

{
    "status": "Published"
}

RISK to break something: HIGH

Assets

1. POST /api/apps/{app}/assets/ does not return the isDuplicate JSON property anymore, it has been replaced with metadata (see example above).

RISK to break something: LOW

Rules

1. GET /api/apps/{app}/rules/ endpoint returns Items-Object instead of a JSON array.

RISK to break something: LOW

Apps

1. GET /api/apps/ endpoint returns Items-Object instead of JSON array.

2. GET /api/apps/{app}/clients/ endpoint returns Items-Object instead of JSON array.

3. GET /api/apps/{app}/languages/ endpoint returns Items-Object instead of JSON array.

4. GET /api/apps/{app}/contributors/ endpoint returns Items-Object instead of custom JSON object.

5. GET /api/apps/{app}/patterns/ endpoint returns Items-Object instead of JSON array.

6. GET /api/apps/{app}/roles/ endpoint returns Items-Object instead of custom JSON object.

RISK to break something: LOW