API encoding configuration

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.

resgateio / resgate