This RFC is work in progress but I’d like to gather feedback before diving deeper into this topic.
As everyone knows we currently have a rather mixed up way of providing and consuming data in the Neos backend. There are multiple (incompatible) ways of representing data that the Neos UI needs and how the server-side accepts data from the Neos UI for changing data.
Since (real) REST is very hard to achieve with the way Flow currently works and how the UI needs data, we should rather aim for a proven format that is extensible and easy to consume.
As there are many different approaches of doing exactly that, we never found a consensus and thus we eneded up with many different “best” practices.
I suggest to settle on a JSON format as the main API format while allowing certain other representations. So all API endpoints must support this format while we allow other formats as applicable.
Using http://jsonapi.org/ as a specification and standard gives us a good standard model of providing an API with many features and saves us from defining all the small details that are needed at some point (error messages, including nested resources, query parameters, etc.).
Example:
{
"links": {
"self": "http://example.com/posts",
"next": "http://example.com/posts?page[offset]=2",
"last": "http://example.com/posts?page[offset]=10"
},
"data": [{
"type": "posts",
"id": "1",
"attributes": {
"title": "JSON API paints my bikeshed!"
},
"relationships": {
"author": {
"links": {
"self": "http://example.com/posts/1/relationships/author",
"related": "http://example.com/posts/1/author"
},
"data": { "type": "people", "id": "9" }
},
"comments": {
"links": {
"self": "http://example.com/posts/1/relationships/comments",
"related": "http://example.com/posts/1/comments"
},
"data": [
{ "type": "comments", "id": "5" },
{ "type": "comments", "id": "12" }
]
}
},
"links": {
"self": "http://example.com/posts/1"
}
}],
"included": [{
"type": "people",
"id": "9",
"attributes": {
"first-name": "Dan",
"last-name": "Gebhardt",
"twitter": "dgeb"
},
"links": {
"self": "http://example.com/people/9"
}
}, {
"type": "comments",
"id": "5",
"attributes": {
"body": "First!"
},
"links": {
"self": "http://example.com/comments/5"
}
}, {
"type": "comments",
"id": "12",
"attributes": {
"body": "I like XML better"
},
"links": {
"self": "http://example.com/comments/12"
}
}]
}
The exact way of how we can define the current endpoints of Neos using this format needs to be figured out. Especially the amount of different endpoints and HTTP verbs needed for the node API needs further investigation.
Nevertheless we should find consensus on 1. a preferred format (JSON) 2. a standard / specification for that format that defines most of the requirements we have for a consistent API.
Personally, I’d have JSON-LD in mind as an API language; but I think just quickly comparing it, JSONAPI covers more ground and is easier to implement as consumer.