API encoding configuration
Closed this issue · 1 comments
Story
When fetching resources using HTTP, the json representation of the data currently includes href's to the linked resources:
Below is an example from resgate-test-app's notesService.notes
resource:
[
{
"href": "/api/notesService/note/1",
"model": {
"id": 1,
"message": "One"
}
},
{
"href": "/api/notesService/note/2",
"model": {
"id": 2,
"message": "Two"
}
}
]
In some cases, a more flat representation is wanted as opposed to the the HATEOAS style currently used.
[
{
"id": 1,
"message": "One"
},
{
"id": 2,
"message": "Two"
}
]
Solution
A new config option should be added:
apiEncoding (string)
Encoding used to represent web resources.
"json"
- JSON encoding with resource references included in the data (default)"jsonFlat"
- JSON encoding with no resource references except for cyclic references.
Example: "json"
Notes
Cyclic references
By using the jsonFlat setting, there is no unambiguous way to represent cyclic references:
Example of the jsonFlat data representation of cyclic.a
:
{
"a": { "href": "cyclic.a" }
}
It is most likely a cyclic reference, but could also be that "a" links to a simple model "b" that just happens to have a single property, href
, with the value "cyclic.a"
.
This is impossible to avoid with jsonFlat
. Users just needs to be aware of the case.
Multiple encodings
The solution opens up for other encodings as well, such as xml
.
Later on (not in this story), it might be possible to use file-endings in the URL to specify which encoding to use.
/api/notesService/notes.json
- Default json encoding with href/api/notesService/notes.flat.json
- jsonFlat encoding/api/notesService/notes.xml
- XML encoding
The setting set for apiEncoding
will be used when no file ending is given.