REC REST API

Please note: This material is for RealEstateCore 3.3. The REST and Edge API formats are being updated to support RealEstateCore 4, but this work is not expected to be complete until REC4 is released in non-preview version, in the fall of 2022.

API Definition (OpenAPI Specification / Swagger)

The REC REST API is generated by machine translation from the ontology using an automated tool. This tool generates REST endpoints for the DTDL Interfaces (i.e., types) declared in an ontology, and generates JSON-LD (see below) schemas for those types based on their Relations (to other types) and Properties (data fields). The API definition is distributed alongside the ontologies in the RealEstateCore GitHub repo.

For interested parties, the design principles defining how the API is implemented are also accessible in that same repo.

JSON-LD Messages

RealEstateCore objects are RDF graph entities, so they can be expressed using the JSON-LD serialization of RDF. JSON-LD is very similar to the JSON syntax web developers typically use, and it has quickly become a de facto standard for RDF transmission on the web. JSON-LD messages can be loaded and examined in a variety of tools, e.g., the JSON-LD Playground, for easy debugging. The REC REST API described below uses JSON-LD messaging. An example REC object (an entrance hallway with two sensors) in JSON-LD is displayed below:

{
  "@context": {
    "@base": "https://example.com/myDataSet#",
    "label": "http://www.w3.org/2000/01/rdf-schema#label",
    "core": "https://w3id.org/rec/core/",
    "device": "https://w3id.org/rec/device/"
  },
  "@id": "EBuildingEntranceHallway",
  "@type": "core:Room",
  "label": "JTH E-Building Entrance Hallway",
  "core:isPartOfBuilding": {
    "@id": "EBuilding",
    "@type": "core:Building"
  },
  "core:containsMountedDevice": [
    {
      "@id": "Thermometer1",
      "@type": "device:Sensor"
    },
    {
      "@id": "LuxMeter1",
      "@type": "device:Sensor"
    }
  ]
}