Skip to content

Latest commit

 

History

History
135 lines (103 loc) · 7.6 KB

rest.md

File metadata and controls

135 lines (103 loc) · 7.6 KB
Raw
title perex date author preferredLang
REST
The Representational State Transfer (REST) API protocol is a standardized approach to building web services that employ HTTP methods to create, read, update, and delete data. The protocol is designed around resources, which are any kind of object, data, or service that can be accessed by the client. Its simplicity, scalability, and performance make REST the most popular protocol for APIs, used extensively in cloud services, mobile services, and social networks.
24.3.2023
Lukáš Hornych
rest
This chapter describes the REST protocol for evitaDB and doesn't make sense for other languages. If you're interested in the details of the REST implementation, please change your preferred language in the upper right corner. The [REST](https://restfulapi.net/) API with an [OpenAPI schema](https://swagger.io/specification/v3/) in evitaDB has been developed to allow users and developers to easily query domain-specific data from evitaDB via universal well-known API standard that REST APIs provide.

The main idea behind our REST API implementation is that the OpenAPI schema is dynamically generated based on evitaDB's internal schemas. This means that users only see the data they can actually retrieve. For example, if you have defined in evitaDB an entity called product with attributes code and name, the OpenAPI schema will contain only these to attributes in the Product entity model with data types equivalent to the ones specified in evitaDB instead of some generic ones.

REST API instances

Used terms

catalog API
A REST API instance that provides ways to query and update actual data (typically entities and related data) of a single catalog, as well as ways to fetch and modify the internal structure of a single catalog. 
		URL pattern: `/rest/{catalog-name}`
	</dd>
	<dt>system API</dt>
	<dd>
		A REST API instance that provides ways to manage evitaDB itself.

		URL pattern: `/rest/system`
	</dd>
</dl>

There isn't a single REST API instance for the whole evitaDB instance. Instead, each evitaDB catalog has its own REST API on its own URL with data only from that particular catalog. In addition, there is one another REST API instance that is reserved for evitaDB administration (e.g., creating new catalogs, removing existing catalogs) called system API.

Each REST API instance URL starts with /rest, followed by the URL-formatted catalog name for specific catalog APIs, or with the reserved system keyword for the above-mentioned system API. You can download OpenAPI schema of each REST API instance by calling GET HTTP request to that base URL which then lists all available endpoints.

URLs of these REST API instances with above-mentioned base URLs are then further suffixed with specific resources. In case of system API those are typically catalogs. In case of catalog API there are resources for individual collections and their actions.

What URLs will be exposed for a set of defined catalogs?

Suppose you have catalogs fashion and electronics. evitaDB would expose the following REST API instances, each with its own relevant OpenAPI schema:

  • /rest/fashion - a catalog API to query or update the actual data of the fashion catalog or its structure
  • /rest/electronic - a catalog API to query or update the actual data of the electronic catalog or its structure
  • /rest/system - the system API to manage evitaDB itself

Structure of APIs

Structure of catalog APIs

A single catalog API for a single catalog contains only a few types of endpoints to retrieve and update data or its internal schema, but most of them are "duplicated" for each collection within that catalog. Also, there is a set of endpoints for retrieving and updating schema of the parent catalog. Each endpoint then takes arguments and returns data specific to a given collection and its schema.

In addition to user-defined collections, there is a "virtual" simplified collection for each catalog in the REST API called entity that allows users to retrieve entities by global attributes without knowing the target collection. However, the entity "collection", has only limited set of endpoints available.

Structure of system API

There is nothing special about the system API, just a set of basic endpoints.

Query language

evitaDB is shipped with its own query language, for which our REST API has its own facade. The main difference between these two is that the evitaDB's original language has generic set of constraints and doesn't care about concrete collection data structure, where the REST version has the same constraints but customized based on collection data structure to provide concrete available constraint for defined data structure.

This custom version of the query language is possible because in our REST API, the query language is dynamically generated based on internal collection schemas to display only constraints that can actually be used to query data (which also changes based on context of nested constraints). This also provides constraint arguments with data types that match the internal data. This helps with the self-documentation because you don't necessarily need to know about the domain model, since the OpenAPI schema can be used to auto-complete the available constraints.

Syntax of query and constraints

Syntax of query and constraints

Recommended usage

Our goal is to design the REST APIs to conform to the RESTful best practices, however this is not always easy, especially when a rather generic database is under the hood, thus there some not so RESTful endpoints. But ultimately, the REST APIs can be used like any other regular REST API, i.e. with standard tools. However, below are our recommendations for tools etc. that we use at evitaDB.

Recommended IDEs

For a desktop IDE to test and explore the REST APIs you can use Insomnia or Postman. For generating documentation from the OpenAPI schema we recommend either Redocly tool or official Swagger Editor which can even generate clients for your programming language.

Recommended client libraries

You can use any basic HTTP client your programming language supports. If you are looking for more, there are code generators that can generate whole typed client in your preferable language from the evitaDB's OpenAPI schemas. Official way of doing this is by using the Swagger Codegen.