Squidex 3.0: API Compatibility

Squidex

Home Cloud Support Github

Search…

Welcome to Squidex

Getting Started

Installation Instructions

Contributing and Developing

Roadmap

Documentation

Introduction and Use Case

Concepts

Software Development Kits

Developer Guides

Squidex 3.0: API Compatibility

The API for Squidex 3.0 contains a lot of changes to 2.0. This document describes the main differences.
The good first: There is no change in the endpoints to retrieve contents or assets, including the GraphQL endpoint.
Motivation
These changes are driven by two requirements:
1.POST and PUT enpoints must return the full entity (e.g. schema object) so that the UI does not have to reason about how the entity will be structured after an updated.
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 lower the list of apps was returned as a JSON array, therefore it was not be possible to add the links to the create 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 contain a _links object now, with all possible operations. If the operation is not possible or the current user does not have the 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 you upload 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 an additional information if this 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 enpoints return the full entity (e.g. schema object) now. This is not a breaking change for you if your client has the following behavior:
1.The client does not break when the JSON response contains additional properties.
2.The client does not break when an enpoint that has returned a 204 No Content status code before, returns 200 OK now (usally the case).
3.The client does not break when an endpoint tht has not returned a JSON response before, returns a response now.
RISK to break something: MEDIUM
Specific changes
Contents
The following endpoints have been removed to be prepared 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, which 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 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

Building a blog with Squidex and Next.js

Last modified 5mo ago

Copy link

Outline

3. Full response objects