Representation Format

Introduction

RESTHeart has three different options for representing the resources:STANDARD, HAL and SHAL (Simplified HAL).

The default representation is controlled by the configuration option default-representation-format .

default-representation-format: STANDARD

The rep query parameter can also be used for switching between representations.

GET /inventory?rep=s HTTP/1.1
GET /inventory?rep=hal HTTP/1.1
GET /inventory?rep=shal HTTP/1.1

Standard Representation

Starting with RESTHeart v4 this is the default representation format.

In the following response the documents of the collection inventory are returned as an array of JSON documents.

Request
GET /inventory HTTP/1.1
Response
HTTP/1.1 200 OK

...

[
  {
    "_id": {
      "$oid": "5d0b4dff2ec9ff0d92ddc2b7"
    },
    "_etag": {
      "$oid": "5d0b4dff2ec9ff0d92ddc2b2"
    },
    "item": "postcard",
    "qty": 45,
    "size": {
      "h": 10,
      "w": 15.25,
      "uom": "cm"
    },
    "status": "A"
  },

  ...

]

Execute the following query to retrieve the metadata of the collection inventory:

Request
GET /inventory/_meta HTTP/1.1
Response
HTTP/1.1 200 OK

...

{
    "_etag": {
        "$oid": "5d1e13dbdde87c62e98a4595"
    },
    "_id": "_meta",
    "meta_field": "metadata_value"
    ...
}

BSON types

MongoDB uses the BSON data format which type system is a superset of JSON’s. To preserve type information, MongoDB adds this extension to the JSON.

For instance, the _id of the following JSON document is an ObjectId.

  {
    "_id": {
      "$oid": "5d0b4e325beb2029a8d1bd5e"
    },
    "item": "paper"

    ...
  }

The strict mode is used on both request and response resource representation and also on the query parameter filter

The following filter won’t find the document since the _id is an ObjectId (and not a String).

Request
GET /inventory?filter={'_id':'5d0b4e325beb2029a8d1bd5e'} HTTP/1.1

The correct request is: 

Request
GET /inventory?filter={'_id':{'$oid':'5d0b4e325beb2029a8d1bd5e'}} HTTP/1.1

Get the names of existing collections

To get the names of the collections of the database restheart (the default configuration binds / to this database).

Request
GET / HTTP/1.1
Response
HTTP/1.1 200 OK

...

[ 
  "inventory",
  "chat",
  "files.bucket" 
]

The root-mongo-resource property is set in default.properties

# The MongoDb resource to bind to the root URI / 
# The format is /db[/coll[/docid]] or '*' to expose all dbs
root-mongo-resource = /restheart
With root-mongo-resource = '*', the request GET / returns the names of existing databases.

HAL

HAL up on 2 simple concepts: Resources and Links

  • Resources have state (plain JSON), embedded resources and links
  • Links have target (href URI) and relations (aka rel)

Example

We’ll get the inventory collection resource and analyze it. A collection represented with HAL has its own propertiesembedded resources (in this case, documents) and link templates (for pagination, sorting, etc).

Request
GET /inventory?rep=hal HTTP/1.1
Response
HTTP/1.1 200 OK
Access-Control-Allow-Credentials: true
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: Location, ETag, X-Powered-By
Connection: keep-alive
Content-Encoding: gzip
Content-Length: 384
Content-Type: application/hal+json
Date: Mon, 08 Jul 2019 12:56:14 GMT
ETag: 5d233840dd860b259a3bad45
X-Powered-By: restheart.org

{
   "_id":"inventory",
   "_etag":{
      "$oid":"5d233840dd860b259a3bad45"
   },
   "metadata_field": "metadata_value",
   "_returned": 6,
   "_embedded":{
      "rh:doc":[
         {
            "_id":{
               "$oid":"5d233aeb93dc53162739e172"
            },
            "_etag":{
               "$oid":"5d233aeb93dc53162739e16d"
            },
            "item":"postcard",
            "qty":45,
            "size":{
               "h":10,
               "w":15.25,
               "uom":"cm"
            },
            "status":"A"
         },
        ...
      ]
   }
}

Properties

In this case, the collection properties comprise the field metadata_field; this is user defined.

The other fields are reserved properties (i.e. are managed automatically by RESTHeart for you); these always starts with _:

Property Description
_type the type of this resource. in this case ‘COLLECTION’ (only returned on hal full mode)
_id the name of the collection
_etag entity tag, used for caching and to avoid ghost writes.
_returned the number of the documents embedded in this representation

Documents as embedded resources

Collection’s embedded resources are the collection documents, recursively represented as HAL documents.

The _embedded property looks like:

{ "_embedded": 
  { "rh:doc": [{
      "_id": {
        "$oid": "5d233aeb93dc53162739e172"
      },
      "_etag": {
        "$oid": "5d233aeb93dc53162739e16d"
      },
      "item": "postcard",
      "qty": 45,
      "size": {
        "h": 10,
        "w": 15.25,
        "uom": "cm"
      },
      "status": "A"
    },
    {
      "_id": {
        "$oid": "5d233aeb93dc53162739e171"
      },
      "_etag": {
        "$oid": "5d233aeb93dc53162739e16d"
      },
      "item": "planner",
      "qty": 75,
      "size": {
        "h": 22.85,
        "w": 30,
        "uom": "cm"
      },
      "status": "D"
    }
  ]}
}
Link Description
self link to itself
first link to the first page
last link to the last page
rh:db templated link for db
rh:coll templated link for collection
rh:document templated link for document
rh:filter templated link for filtering
rh:sort templated link for sorting
rh:indexes link to the collection indexes resource
rh:paging templated link for paging
curies

(compacts URIes) bind links to documentation. For instance the rh:db rel is documented at https://restheart.org/curies/2.0/db.html

The _links property looks like:

{ "_links": { 
  "self": {
    "href": "/inventory?hal=f"
  },
  "first": {
    "href": "/inventory?pagesize=100&hal=f"
  },
  "next": {
    "href": "/inventory?page=2&pagesize=100&hal=f"
  },
  "rh:coll": {
    "href": "//{collname}",
    "templated": true
  },
  "rh:document": {
    "href": "/inventory/{docid}{?id_type}",
    "templated": true
  },
  "rh:indexes": {
    "href": "/inventory/_indexes"
  },
  "rh:filter": {
    "href": "/inventory{?filter}",
    "templated": true
  },
  "rh:sort": {
    "href": "/inventory{?sort_by}",
    "templated": true
  },
  "rh:paging": {
    "href": "/inventory{?page}{&pagesize}",
    "templated": true
  }
}

HAL Mode

The query parameter hal controls the verbosity of HAL representation. Valid values are hal=c (for compact) and hal=f (for full); the default value (if the param is omitted) is compact mode.

When hal=f is specified, the representation is more verbose and includes special properties (such as links).

Simplified HAL

Up to RESTHeart 3.x SHAL was also called PLAIN_JSON

In the following response the collection /inventory has the properties _id, _etag, metadata_field and two embedded documents and the special property _returned

Request
GET /inventory?rep=shal HTTP/1.1
Response
HTTP/1.1 200 OK

...

{
  "_embedded": [
    {
      "_id": {
        "$oid": "5d0b4dff2ec9ff0d92ddc2b7"
      },
      "_etag": {
        "$oid": "5d0b4dff2ec9ff0d92ddc2b2"
      },
      "item": "postcard",
      "qty": 45,
      "size": {
        "h": 10,
        "w": 15.25,
        "uom": "cm"
      },
      "status": "A"
    }
  ],
  "_id": "inventory",
  "_etag": {
    "$oid": "5d1e13dbdde87c62e98a4595"
  },
  "metadata_field": "metadata_value",
  "_returned": 6
}