Skip to main content
Version: Next

Introduction

note

You are currently looking at a work in progress version of the Relynk API documentation. Consider the underlying APIs and messaging formats as stable, but we strive to make the documentation as developer friendly as possible. If you feel anything is missing please reach out to hello@relynk.io, any feedback would be much appreciated.

Introduction

Relynk implements the Real Estate Core (REC) open-source API specification. This document aims to provide a comprehensive overview of the principles, requirements, and functionalities of the REC APIs, making it easier for developers to understand and utilize these APIs effectively in real estate applications.

caution

Prerequisites​

This guide assumes you are familiar with Real Estate Core. If you are not, please refer to the following documentation: Introduction to Real Estate Core.

Overview​

The RealEstateCore REST API, herein referred to as REC API, is designed to serve as the backbone for applications within the real estate domain, offering a structured and standardized way to access and manipulate real estate data. The REC API is based on the RealEstateCore ontology, leveraging semantic web technologies to provide a robust and extensible framework for real estate data exchange.

Principles​

The REC Consortium has laid down several principles guiding the development and usage of the REC APIs:

  • Narrow Scope with Guidance for Evolution: The initial REC API specification is deliberately narrow, offering guidance on how the specification may evolve over time.
  • Adherence to REST API Best Practices: The REC API strives to follow REST API best practices closely.
  • Ontology as an Information Model: REC itself is an ontology and serves as the information model for the API. All service endpoints, filters, etc., must adhere to REC terminology.
  • Embrace Linked Data Concepts: The REC API format incorporates linked data concepts, prominently JSON-LD, reflecting its roots in the semantic web.
  • Compliance and Extendibility: The specification outlines the minimum set of requirements for an API to be considered "RealEstateCore Compliant." It also includes optional requirements and encourages the implementation of additional functionality.
  • Discovery: For API discoverability, especially regarding ontology extensions, the REC API supports programmatic discovery mechanisms.

Service Endpoints and Operations​

The REC API supports CRUD operations following the conventional HTTP verb mapping:

  • Create: HTTP POST
  • Retrieve: HTTP GET
  • Update: HTTP PATCH for specific attributes and HTTP PUT for full individuals
  • Delete: HTTP DELETE

Resource Paths and Queries​

  • Resource Paths: The API uses resource paths that reflect the REC class hierarchy, with provisions for accessing both collections of individuals and specific individuals.
  • Queries: The REC API supports simple queries with traditional query parameters, as well as more complex operator-based queries for filtering.

Pagination and Sorting​

  • Pagination: Implements Hydra PartialCollectionView for managing collections of resources.
  • Sorting: Follows JSON:API standards, recommending support for sorting on all potentially returned REC properties.

Responses and Error Handling​

  • JSON-LD: All responses are formatted in JSON-LD, adhering to the principles of linked data and semantic web.
  • Error Handling: While the REC Consortium is still evaluating practices for error handling, the use of Hydra Status and Error classes is under consideration.