Plain JSON representation in upcoming RESTHeart 3.0

 

Plain JSON representation in upcoming RESTHeart 3.0

07 September 2016  • SoftInstigate Team
Categories: en, technology  • Tags: restheart

The upcoming RESTHeart 3.0 release is going to bring a new, exiting feature: plain JSON representation of resources besides the usual HAL format. This dramatically simplifies handling with the API and answers some feedbacks we got from the community; as usual, you asked, we listened!

RESTHeart has been using the popular Hypertext Application Language since its inception.

The reason behind this choice is simple: HAL is elegant and fits perfecly in the nested nature of resources such as dbs, collection and documents.

On the other hand HAL is indeed verbose! As example a collection resource is represented in the response as follows:

$ http http 127.0.0.1:8080/db/coll?pagesize=3
HTTP/1.1 200 OK
...
{
  "_id": "coll",
  "_returned": 3,
  "_etag": {
      "$oid": "572857ae2d174c0a73ab7b9a"
  },  
  "_embedded": {
      "rh:doc": [
          {
              "_etag": {
                  "$oid": "572858052d174c0a73ab7b9e"
              },
              "_id": {
                  "$oid": "57285805bf4793c10dd5dbfd"
              },
              "text": "Ma sedendo e mirando interminati spazi al di la di quello"
          },
          {
              "_etag": {
                  "$oid": "572857ef2d174c0a73ab7b9d"
              },
              "_id": {
                  "$oid": "572857efbf4793c10dd5dbfc"
              },
              "text": "dell'ultimo orizzonte il guardo esclude"
          },
          {
              "_etag": {
                  "$oid": "572857e32d174c0a73ab7b9c"
              },
              "_id": {
                  "$oid": "572857e3bf4793c10dd5dbfb"
              },
              "text": "e questa siepe che da tanta parte"
          }
      ]
  }
}

__

You can note that the collection is represented with its properties (_id , _etag, etc) and its nested resources, i.e. the documents! Those are in the array rh:doc in the object _embedded .

Other resources (dbs, file buckets, etc) are represented in a similar way.

SoftInstigate developed an angular.js module to make simple to interact with such representation format (and the authentication). Check it at angular-restheart github repo.

With the 3.0 release you will be able to pass the pj query parameter (where pj stands for Plain Json). It switches the representation to a simplified form where:

  • GET / returns an array of datases objects
  • GET /db returns an array of collections objects
  • GET /db/coll returns an array of documents objects

You can download the 3.0-SNAPSHOT from sonatype

With pj the response looks like:

$ http 127.0.0.1:8080/db/coll?pj\&pagesize=3
HTTP/1.1 200 OK
...
[
    {
        "_etag": {
            "$oid": "572858052d174c0a73ab7b9e"
        },
        "_id": {
            "$oid": "57285805bf4793c10dd5dbfd"
        },
        "text": "Ma sedendo e mirando interminati spazi al di la di quello"
    },
    {
        "_etag": {
            "$oid": "572857ef2d174c0a73ab7b9d"
        },
        "_id": {
            "$oid": "572857efbf4793c10dd5dbfc"
        },
        "text": "dell'ultimo orizzonte il guardo esclude"
    },
    {
        "_etag": {
            "$oid": "572857e32d174c0a73ab7b9c"
        },
        "_id": {
            "$oid": "572857e3bf4793c10dd5dbfb"
        },
        "text": "e questa siepe che da tanta parte"
    }
]

__

How cool is that?


 

Comments