v8 v7 v6 v5 v4 v3
Edit Page

Get Started

Upgrade to v5

Roadmap

Content API

Management API

Securing Requests

Plugins

Other Features

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.

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" }

JSON Mode

JSON Mode is available from RESTHeart v4.1

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")}

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

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"
            }
        ]
    }
}
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
}