HATEOAS without sending the HTTP links in the response - hateoas

Question

Hi there REST HATEOAS experts !
Here is a typical JSON response from an HATEOAS service
{
links: {
'add': 'http://myhost/API/students',
'csv-export': 'http://myhost/API/students/export'
},
list: [
{id: '1', name: 'John Doe', links: {'see': 'http://myhost/API/students/1'},
{id: '2', name: 'Jane Doe', links: {'see': 'http://myhost/API/students/2'},
...
]
}
From this we can see that sending full HTTP(s) links along with the response is
very space consuming (yes, I know about gzip)
hard to read (imagine when there are 1000 elements in list)
not sufficient since you still don't know which method to use (nor which content you need to send)
So what I am doing is the following :
{
resType: 'studentsCollection',
rels: ['add','csv-export'],
list: [
{id: '1', name: 'John Doe', resType: 'studentCollectionItem', rels: ['see'],
{id: '2', name: 'Jane Doe', resType: 'studentCollectionItem', rels: ['see'],
...
]
}
And I provide additional endpoints :
/resTypes/studentsColelction/rels
{
resType: 'studentsCollection',
links: {
'add': {method: 'POST', url: '/students', contentType: 'studentForm', resultType: 'studentId'},
'csv-export': {method: 'GET', url: '/students/export', contentType: 'studentCriteria', resultType: 'binary'}
}
}
/resTypes/studentCollectionItem/rels
{
resType: 'studentCollectionItem',
links: {
'see': {method: 'GET', url: '/students/{id}', resultType: 'studentEntity'}
}
}
There also exists /resTypes which return all the resTypes at once to avoid multiple roundtrips

Answer 1

It sounds like JSON Hyper-Schema is a good fit for you. JSON Hyper-Schema is a hypermedia media type that you can use to apply links to your raw data without needing to modify your data.
Let's say you have this JSON response data
{
"list": [
{
"id": "1",
"name": "foo"
},
{
"id": "2",
"name": "bar"
}
]
}
That data can then be describedby the following Hyper-Schema.
{
"title": "Students",
"type": "object",
"properties": {
"list": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": { "type": "string" },
"name": { "type": "string" }
},
"links": [
{ "rel": "student", "href": "/students/{id}" }
]
}
}
}
"links": [
{
"rel": "create", "href": "/students",
"method": "POST",
"schema": { "$ref": "/schemas/createStudent" }
}
]
}
The Hyper-Schema is like a hypermedia template that can be applied to a plain JSON document to transform a plain JSON response into a hypermedia enabled JSON response. Notice the URL template in the example /students/{id}. The {id} variable is filled in from the instance data. Therefore, the first item in the list has a link /students/1 and the second item has a link /students/2. This allows you to not have to duplicate all of that link boilerplate in every response.
You use a header Link to associate a JSON response with a Hyper-Schema
Link: </schema/students>; rel="describedby"
At this point you might be thinking, "that's nice but the extra request to get the Hyper-Schema for each response takes even more resources than sending bloated responses". That's why you should design your system so that Hyper-Schemas are cacheable forever. Then when the client sees a describedby link for a resource it already has, it just uses it's cached version. No additional request needed. If you ever need to change the Hyper-Schema, just change the describedby link to a different URI /schema/v2/student and the client will do a one time download of the new Hyper-Schema. Despite the occasional extra request to retrieve a Hyper-Schema, your overall bandwidth usage should be less than if you send all of your links in every request.
This example uses the draft-04 version JSON Hyper-Schema. Since draft-04, JSON Schema has been "under new management" so to speak. Although draft-04 is far from perfect, I'm personally not happy with the direction they have taken the spec since draft-04. However, I encourage you to checkout the latest draft (currently draft-07) as well and make your own decision.