REST API

We recommend using one of Baqend's SDKs to develop an application, but you can also directly access the underlying communication protocols:
This document describes Baqend's HTTP REST API which is used for request-response interaction between client and server.
(For information on the messaging protocol that enables real-time communication between client and server, see our Websocket API Docs.)

Overview

The REST API is split up into eleven different categories (see our Swagger documentation).
In this section, however, we focus on the most typical use cases:

CRUD (Create, Read, Update, Delete): The CRUD API offers the ability to save, load, update, and delete objects in the database.
Each class defined in the schema has a separate endpoint: https://<app-name>.app.baqend.com/v1/db/<class-name>

query: To load multiple objects of one particular class, you can execute a MongoDB query by sending a GET request with URI component encoded GET parameters to https://<app-name>.app.baqend.com/v1/db/<class-name>/query.
The response will contain the query result.
The available parameters are: q (MongoDB query), count (integer), sort (MongoDB sort), start (integer)

user:
The user API enables authentication and authorization. It offers the ability to register and login users, change passwords, and usernames.

Note:
To ensure backward compatibility, all endpoints start with an API version number. The current version is v1: https://<app-name>.app.baqend.com/v1.

CRUD

Authentication

Baqend uses a token-based authentication mechanism. Register and login requests
return the header baqend-authorization-token. The value of this header is the authorization token, which must be
attached as the authorization header to permission-protected
CRUD requests: authorization: BAT <token>

CRUD requests may return a renewed token in the baqend-authorization-token header. If this happens, the renewed token must be used for all subsequent requests.

Create

A POST request with a JSON payload sent to https://<app-name>.app.baqend.com/v1/db/<class-name> will create a new object of type
class-name; it will return the created object with additional metadata fields like updatedAt, createdAt, and id.
The following example creates an object for the class Message with the string attribute text.

Read

To load a particular object, send a GET request to https://<app-name>.app.baqend.com/v1<id>.
Here, the <id> value corresponds to the id value in the JSON representation of an object (e.g. as returned after creating an object).

Update

To update the object with ID <id>, send a PUT request with the updated JSON to https://<app-name>.app.baqend.com/v1<id>.
If you set the if-match header to your current version of the object, the update will only be executed if this version is still up-to-date.
Thus, you can prevent accidentally overwriting changes made by others.

Delete

To delete the object with ID <id>, send a DELETE request to https://<app-name>.app.baqend.com/v1<id>.
As with updates, you can also prevent accidentally deleting changes made by others:
To this end, set the if-match request header to your current version of the object; thus, the object will only be deleted if your object version is still up-to-date.

User Management

To use Baqend's user management system, you have to use the user API. It offers the ability
to register and login users.

Baqend uses a token-based authentication mechanism. Register and login requests return the header baqend-authorization-token.
The value of this header is the authorization token, which must be attached as the authorization header to ACL-protected CRUD requests:
authorization: BAT <token>

Register

To register a user, send a POST request to https://<app-name>.app.baqend.com/v1/db/User/register. If you've
defined more fields in the user schema, you can pass additional data to the user object in the request body.

Query

To query the data of one class, you can write a MongoDB query via
GET request to https://<app-name>.app.baqend.com/v1/db/<class-name>/query.
You will receive the query result in the response body.
Note that GET parameters have to be URI component encoded.