(Non-HAL) JSON output

[sgnn7]

While I understand the reasons for having the HAL+JSON output, it feels like there could be numerous advantages to also having pure JSON that would support modular/generic API interfaces.

For example, a generic API call to something like http GET 127.0.0.1:8080/myfirstdb/myfirstcoll should really return something more like the regular JSON in most web programming frameworks:

{{"name": "restheart","rating": "super cool"},{ "name": "mongodb","rating": "hyper cool"}}

instead of the _embedded, rh:doc, and all the other _* tags that HAL injects; yes some of this can be filtered but it would be nice to have a simple HAL_JSON = true/false flag that switches between these two.

tl;dr
Primary reasons for ability to also use non-HAL JSON:

• Much simpler and more portable client code
• Reduced network use by about 50% or more for some objects
• Ease of readability
• Compatibility with most web frameworks out of the box

[ujibang]

Hi,

the upcoming 1.1 release does actually have this feature! It was a feedback we already had and you confirm this need.

There is a new query parameter called hal that can be f (full) or c (compact); the default value (if you omit it) is compact.

On compact mode, the curies, templated links, pagination links (for root, db and collection resources) are not included in the response.

However this has nothing to do with HAL. The representation is still HAL (that is json anyway), where resources have properties, links and embedded resources. So root embeds dbs that embed collections that embed documents; links allow to navigate the API that we think is a big plus.

I don't get the point about the "Compatibility with most web frameworks out of the box". hal+json media type is json anyway so there shouldn't be any problem; can you elaborate on this?

An example is:

Compact HAL mode

$ http -a a:a GET 127.0.0.1:8080/test/bands/Pink%20Floyd
HTTP/1.1 200 OK
...

{
    "_etag": {
        "$oid": "562e962ec2e6a475e8fe3afe"
    }, 
    "_id": "Pink Floyd", 
    "_links": {
        "albums": {
            "href": "/test/albums?filter={'_id':{'$in':['The Piper at the Gates of Dawn','A Saucerful of Secrets','More','Ummagumma','Atom Heart Mother','Meddle','Obscured by Clouds','The Dark Side of the Moon','Wish You Were Here','Animals','The Wall','The Final Cut','A Momentary Lapse of Reason','The Division Bell','The Endless River']}}"
        }, 
        "curies": [], 
        "self": {
            "href": "/test/bands/Pink Floyd"
        }
    }, 
    "albums": [
        "The Piper at the Gates of Dawn", 
        "A Saucerful of Secrets", 
        "More", 
        "Ummagumma", 
        "Atom Heart Mother", 
        "Meddle", 
        "Obscured by Clouds", 
        "The Dark Side of the Moon", 
        "Wish You Were Here", 
        "Animals", 
        "The Wall", 
        "The Final Cut", 
        "A Momentary Lapse of Reason", 
        "The Division Bell", 
        "The Endless River"
    ]
}

I think I'll remove the _lastupdated_on and _type properties as well in compact mode (those are not really properties stored in the db, but injected by RESTHeart).

You'll notice the empty array curies between the _links. We wanted to remove it but we kept it due a bug in the HAL browser (mikekelly/hal-browser#71).

Full HAL mode

$ http -a a:a GET 127.0.0.1:8080/test/bands/Pink%20Floyd?hal=f
HTTP/1.1 200 OK
...

{
    "_etag": {
        "$oid": "562e962ec2e6a475e8fe3afe"
    }, 
    "_id": "Pink Floyd", 
    "_lastupdated_on": "2015-10-26T21:07:58Z", 
    "_links": {
        "albums": {
            "href": "/test/albums?filter={'_id':{'$in':['The Piper at the Gates of Dawn','A Saucerful of Secrets','More','Ummagumma','Atom Heart Mother','Meddle','Obscured by Clouds','The Dark Side of the Moon','Wish You Were Here','Animals','The Wall','The Final Cut','A Momentary Lapse of Reason','The Division Bell','The Endless River']}}"
        }, 
        "curies": [
            {
                "href": "http://restheart.org/curies/1.0/{rel}.html", 
                "name": "rh", 
                "templated": true
            }
        ], 
        "rh:coll": {
            "href": "/test/bands"
        }, 
        "rh:document": {
            "href": "/test/bands/{docid}{?id_type}", 
            "templated": true
        }, 
        "self": {
            "href": "/test/bands/Pink Floyd"
        }
    }, 
    "_type": "DOCUMENT", 
    "albums": [
        "The Piper at the Gates of Dawn", 
        "A Saucerful of Secrets", 
        "More", 
        "Ummagumma", 
        "Atom Heart Mother", 
        "Meddle", 
        "Obscured by Clouds", 
        "The Dark Side of the Moon", 
        "Wish You Were Here", 
        "Animals", 
        "The Wall", 
        "The Final Cut", 
        "A Momentary Lapse of Reason", 
        "The Division Bell", 
        "The Endless River"
    ]
}

[ujibang]

just committed a change, in hal compact mode, the special properties (_type, _lastupdated_on and _created_on) are not returned anymore.

[sgnn7]

@ujibang Sweet! Thank you guys!

PS: As for the compatibility issues, the problem is not parsing the JSON but the need for the JSON to be navigated by app logic to get to the expected meat of the data: result['_embedded']['rh:doc'] which most frameworks can't handle without manually adding logic to them out of the box.

[ujibang]

I see your point.

We choose HAL because a collection (which embeds documents) must be navigated anyway and we preferred to relay on an established representation standard format...

we need this embedding approach because in RESTHeart dbs, and collections can have their own properties too. Some special properties are metadata and can modify the responses. See for instance how the document references are managed here or the request checkers here

[ujibang]

@sgnn7 for your information release 1.1 is out with compact HAL format.
more info at http://www.softinstigate.com/blog/2015/12/08/what-is-new-in-RESTHeart-1.1.0/

[sgnn7]

@ujibang Awesome! Thanks for pinging me on this!

[DaBlitzStein]

I've tried to use this software with at least 8 clients from the environment of the gaming, corporative, etc. HAL mode is a shame and totally uncompatible with modern interfaces.
Flag to remove hal totally and this thing of "_embedded" please.

[ujibang]

Hi @DaBlitzStein,

we agree with you and actually introduced the plain json representation format long ago.

HAL is still available via configuration:

default-representation-format: PLAIN_JSON | HAL

documents of a collection are still in the _embedded array.

You can get the documents of a collection as an array just passing the np query parameter (np stands for "No collection Properties".

GET /db/coll?np

[ { doc1 }, 
  { doc2 }, 
  { doc3 }, 
  ...
]

To get the properties of the collections (such as _size, _returned or metadata properties like aggrs) just don't specify np: in this case you find the documents in _embedded array

{
  "_embedded":  [ { doc1 }, 
          { doc2 }, 
          { doc3 }, 
          ...
  ],
  "_ret": 100,
  "_count":  2324,
  "_aggrs": [ ... ]

Are you happy with this? We are open to suggestions...

[mkjsix]

@ujibang I think this aspect should be better documented by us, the plain JSON representation with no properties it's an important feature but probably not enough highlighted.