Representation Format
- BSON types
- Json Mode
Other representation formats
- HAL
- Simplified HAL

Representation Format

The following table summarizes how resources are represented

resource	represented as	example
root `/`	paginated array of existing db names	`["db1", "db2"]`
db `/<db-name>`	paginated array of collection/buckets names that exist in the db	`["collection1", "file.bucket"]`
collection `<db-name>/<collection-name>`	paginated array of documents of the collection	`[ {"_id": "doc1, "foo": "bar" }, {"_id": "doc2, "foo": "bar" } ]`
document	JSON object	`{"_id": "doc1, "foo": "bar" }`

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

JSON Mode

JSON can only directly represent a subset of the types supported by BSON. To preserve type information, RESTHeart adds the following extensions to the JSON format.

The query parameter jsonMode allows to specify the JSON Mode

jsonMode	Description
none	Standard RESTHeart representation
STRICT	JSON representation with type information for specific cases
EXTENDED	Extended JSON representation with full type information
RELAXED	Standard relaxed extended JSON representation
SHELL	This output mode will attempt to produce output that corresponds to what the MongoDB shell actually produces when showing query results

Standard RESTHeart representation

GET locahost:8080/coll/5d7a4b59cf6eeb5fb1686613 HTTP/1.1

{
    "_etag": {
        "$oid": "5d7a4f10af0e1b77a7731d05"
    },
    "_id": {
        "$oid": "5d7a4b59cf6eeb5fb1686613"
    },
    "a": 1,
    "b": 1.0,
    "big": 1568295769260,
    "timestamp": {
        "$date": 1568295769260
    }
}

Strict representation

GET locahost:8080/coll/5d7a4b59cf6eeb5fb1686613?jsonMode=strict HTTP/1.1

HTTP/1.1 200 OK

{
    "_etag": {
        "$oid": "5d7a4f10af0e1b77a7731d05"
    },
    "_id": {
        "$oid": "5d7a4b59cf6eeb5fb1686613"
    },
    "a": 1,
    "b": 1.0,
    "big": {
        "$numberLong": "1568295769260"
    },
    "timestamp": {
        "$date": 1568295769260
    }
}

Extended representation

GET locahost:8080/coll/5d7a4b59cf6eeb5fb1686613?jsonMode=extended HTTP/1.1

HTTP/1.1 200 OK

{
    "_etag": {
        "$oid": "5d7a4f10af0e1b77a7731d05"
    },
    "_id": {
        "$oid": "5d7a4b59cf6eeb5fb1686613"
    },
    "a": {
        "$numberInt": "1"
    },
    "b": {
        "$numberDouble": "1.0"
    },
    "big": {
        "$numberLong": "1568295769260"
    },
    "timestamp": {
        "$date": {
            "$numberLong": "1568295769260"
        }
    }
}

Relaxed representation

GET locahost:8080/coll/5d7a4b59cf6eeb5fb1686613?jsonMode=relaxed HTTP/1.1

HTTP/1.1 200 OK

{
    "_etag": {
        "$oid": "5d7a6c61bd8a0d69516bbf55"
    },
    "_id": {
        "$oid": "5d7a4b59cf6eeb5fb1686613"
    },
    "a": 1,
    "b": 1.0,
    "big": 1568295769260,
    "timestamp": {
        "$date": "2019-09-12T13:42:49.26Z"
    }
}

Shell representation

SHELL JSON Mode is very useful since it allows to use the response body directly in the mongoshell!

GET locahost:8080/coll/5d7a4b59cf6eeb5fb1686613?jsonMode=shell HTTP/1.1

HTTP/1.1 200 OK

Content-Type: application/javascript

{"_id":ObjectId("5d7a4b59cf6eeb5fb1686613"),"_etag":ObjectId("5d7a6d13bd8a0d69516bbf56"),"timestamp":ISODate("2019-09-12T13:42:49.260Z"),"a":1,"b":1.0,"big":NumberLong("1568295769260"),"verybig":NumberLong("5887391606")}

Other representation formats

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

HAL and SHAL are deprecated in version 6.0 and will likely be removed in a future release.

The default representation can be 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

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 properties, embedded 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"
            }
        ]
    }
}

Links

_links are only returned on hal full mode. The only exception are with relationships. If a collection defines a relationship, the representation of the documents always include the links to related data.

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

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
}

Looking for Cloud Services or Professional Support? Check restheart.com

Overview

Setup

Framework

Security

MongoDB

REST API

GraphQL API

Websocket API

Representation Format