CRUD persistence over schema-backed tables - save, update, upsert, and delete single or bulk objects, plus rich search with where clauses, paging, sorting, relations, grouping, and aggregate functions.
openapi: 3.0.1
info:
title: Backendless REST API
description: >-
REST API for the Backendless backend-as-a-service platform. Every request is
addressed to a specific application using its application id and REST API key,
both carried as path segments immediately after the host. Authenticated
operations additionally require the user-token returned by the login endpoint,
sent in the user-token request header. This specification covers the core
documented services - Data, Users, Files, Messaging and Push, Geo, Cache,
Atomic Counters, and Cloud Code custom service invocation.
termsOfService: https://backendless.com/terms-of-service/
contact:
name: Backendless Support
url: https://support.backendless.com
version: '1.0'
servers:
- url: https://api.backendless.com/{app-id}/{rest-api-key}
description: Backendless application endpoint
variables:
app-id:
default: APP_ID
description: The application id assigned to your Backendless app.
rest-api-key:
default: REST_API_KEY
description: The REST API key generated for your Backendless app.
security:
- userToken: []
tags:
- name: Data
description: CRUD and search over schema-backed database tables.
- name: Users
description: User registration, authentication, and session management.
- name: Files
description: File and directory storage operations.
- name: Messaging
description: Publish-subscribe messaging, push notifications, and email.
- name: Geo
description: Geolocation point management and proximity search.
- name: Cache
description: Server-side key/value cache.
- name: Counters
description: Thread-safe atomic counters.
- name: CloudCode
description: Invocation of custom serverless API services.
paths:
/data/{table-name}:
post:
operationId: createObject
tags:
- Data
summary: Save a single object
description: >-
Persists a new object into the named table. The request body must not
include an objectId; Backendless assigns one and returns the saved object.
parameters:
- $ref: '#/components/parameters/TableName'
requestBody:
required: true
content:
application/json:
schema:
type: object
additionalProperties: true
example:
name: Bob
age: 20
responses:
'200':
description: The saved object with a system-assigned objectId.
content:
application/json:
schema:
$ref: '#/components/schemas/DataObject'
'400':
$ref: '#/components/responses/Error'
get:
operationId: findObjects
tags:
- Data
summary: Find objects
description: >-
Retrieves a collection of objects from a table with optional filtering,
paging, sorting, relations, grouping, and property projection.
parameters:
- $ref: '#/components/parameters/TableName'
- name: where
in: query
description: SQL-like search clause applied to the table.
schema:
type: string
- name: pageSize
in: query
description: Number of objects to return per page (max 100).
schema:
type: integer
default: 10
- name: offset
in: query
description: Zero-based index of the first object to return.
schema:
type: integer
default: 0
- name: sortBy
in: query
description: Comma-separated list of properties to sort by.
schema:
type: string
- name: property
in: query
description: Comma-separated list of properties (or aggregates) to return.
schema:
type: string
- name: loadRelations
in: query
description: Comma-separated list of related columns to eager-load.
schema:
type: string
- name: groupBy
in: query
description: Comma-separated list of columns to group results by.
schema:
type: string
responses:
'200':
description: A collection of matching objects.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/DataObject'
'400':
$ref: '#/components/responses/Error'
/data/{table-name}/{object-id}:
get:
operationId: getObjectById
tags:
- Data
summary: Retrieve object by id
parameters:
- $ref: '#/components/parameters/TableName'
- $ref: '#/components/parameters/ObjectId'
responses:
'200':
description: The requested object.
content:
application/json:
schema:
$ref: '#/components/schemas/DataObject'
'404':
$ref: '#/components/responses/Error'
put:
operationId: updateObject
tags:
- Data
summary: Update a single object
description: Updates the properties supplied in the body for the identified object.
parameters:
- $ref: '#/components/parameters/TableName'
- $ref: '#/components/parameters/ObjectId'
requestBody:
required: true
content:
application/json:
schema:
type: object
additionalProperties: true
responses:
'200':
description: The updated object.
content:
application/json:
schema:
$ref: '#/components/schemas/DataObject'
'400':
$ref: '#/components/responses/Error'
delete:
operationId: deleteObject
tags:
- Data
summary: Delete a single object
parameters:
- $ref: '#/components/parameters/TableName'
- $ref: '#/components/parameters/ObjectId'
responses:
'200':
description: Deletion timestamp.
content:
application/json:
schema:
type: object
properties:
deletionTime:
type: integer
format: int64
'404':
$ref: '#/components/responses/Error'
/data/{table-name}/count:
get:
operationId: countObjects
tags:
- Data
summary: Count objects
description: Returns the number of objects in a table matching an optional where clause.
parameters:
- $ref: '#/components/parameters/TableName'
- name: where
in: query
schema:
type: string
responses:
'200':
description: The matching object count.
content:
application/json:
schema:
type: integer
/users/register:
post:
operationId: registerUser
tags:
- Users
summary: Register a new user
security: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/RegistrationRequest'
responses:
'200':
description: The created user object.
content:
application/json:
schema:
$ref: '#/components/schemas/User'
'400':
$ref: '#/components/responses/Error'
/users/login:
post:
operationId: loginUser
tags:
- Users
summary: Log in a user
description: >-
Authenticates a user with an identity (e.g. email) and password. The
response includes a user-token that must be sent in the user-token header
on subsequent authenticated requests.
security: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/LoginRequest'
responses:
'200':
description: Authenticated user object including user-token.
content:
application/json:
schema:
$ref: '#/components/schemas/User'
'401':
$ref: '#/components/responses/Error'
/users/logout:
get:
operationId: logoutUser
tags:
- Users
summary: Log out the current user
responses:
'200':
description: The session was invalidated.
'401':
$ref: '#/components/responses/Error'
/users/restorepassword/{identity}:
get:
operationId: restorePassword
tags:
- Users
summary: Initiate password recovery
security: []
parameters:
- name: identity
in: path
required: true
description: The user identity (e.g. email) to recover.
schema:
type: string
responses:
'200':
description: A recovery email was sent.
'400':
$ref: '#/components/responses/Error'
/files/{path}:
post:
operationId: uploadFile
tags:
- Files
summary: Upload a file
description: >-
Uploads a file to the given path in the hosted file repository. Missing
directories in the path are created automatically.
parameters:
- name: path
in: path
required: true
description: Directory path and filename, e.g. images/photo.png.
schema:
type: string
- name: overwrite
in: query
description: Whether to overwrite an existing file at the path.
schema:
type: boolean
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
properties:
file:
type: string
format: binary
responses:
'200':
description: Metadata for the uploaded file.
content:
application/json:
schema:
$ref: '#/components/schemas/FileInfo'
'400':
$ref: '#/components/responses/Error'
delete:
operationId: deleteFile
tags:
- Files
summary: Delete a file or directory
parameters:
- name: path
in: path
required: true
schema:
type: string
responses:
'200':
description: The file or directory was deleted.
'404':
$ref: '#/components/responses/Error'
/messaging/{channel-name}:
post:
operationId: publishMessage
tags:
- Messaging
summary: Publish a message
description: >-
Publishes a message to a named channel. The same channel endpoint is used
to dispatch mobile push notifications by supplying push headers and a
delivery policy (singlecast or broadcast) in the body.
parameters:
- name: channel-name
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PublishMessageRequest'
responses:
'200':
description: Publish acknowledgement with a message id and status.
content:
application/json:
schema:
$ref: '#/components/schemas/MessageStatus'
'400':
$ref: '#/components/responses/Error'
/messaging/{channel-name}/{subscription-id}:
get:
operationId: pollMessages
tags:
- Messaging
summary: Poll for messages
description: Retrieves messages buffered for an established polling subscription.
parameters:
- name: channel-name
in: path
required: true
schema:
type: string
- name: subscription-id
in: path
required: true
schema:
type: string
responses:
'200':
description: Buffered messages for the subscription.
content:
application/json:
schema:
type: object
additionalProperties: true
'400':
$ref: '#/components/responses/Error'
/messaging/email:
post:
operationId: sendEmail
tags:
- Messaging
summary: Send a basic email
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/EmailRequest'
responses:
'200':
description: The email was queued for delivery.
'400':
$ref: '#/components/responses/Error'
/geo/points:
get:
operationId: findGeoPoints
tags:
- Geo
summary: Search geo points
description: >-
Finds geo points by category and proximity. Supply latitude/longitude with
a radius and units for a radius search.
parameters:
- name: categories
in: query
schema:
type: string
- name: lat
in: query
schema:
type: number
format: double
- name: lon
in: query
schema:
type: number
format: double
- name: radius
in: query
schema:
type: number
format: double
- name: units
in: query
schema:
type: string
enum: [METERS, KILOMETERS, MILES, YARDS, FEET]
responses:
'200':
description: Matching geo points.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/GeoPoint'
'400':
$ref: '#/components/responses/Error'
post:
operationId: saveGeoPoint
tags:
- Geo
summary: Add a geo point
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/GeoPoint'
responses:
'200':
description: The saved geo point.
content:
application/json:
schema:
$ref: '#/components/schemas/GeoPoint'
'400':
$ref: '#/components/responses/Error'
/cache/{key}:
put:
operationId: cachePut
tags:
- Cache
summary: Put a value into cache
parameters:
- $ref: '#/components/parameters/CacheKey'
- name: timeout
in: query
description: Time-to-live in milliseconds.
schema:
type: integer
format: int64
requestBody:
required: true
content:
application/json:
schema:
type: object
additionalProperties: true
responses:
'200':
description: The value was cached.
'400':
$ref: '#/components/responses/Error'
get:
operationId: cacheGet
tags:
- Cache
summary: Retrieve a cached value
parameters:
- $ref: '#/components/parameters/CacheKey'
responses:
'200':
description: The cached value.
content:
application/json:
schema:
type: object
additionalProperties: true
'404':
$ref: '#/components/responses/Error'
delete:
operationId: cacheDelete
tags:
- Cache
summary: Delete a cached value
parameters:
- $ref: '#/components/parameters/CacheKey'
responses:
'200':
description: The cached value was removed.
/cache/{key}/check:
get:
operationId: cacheContains
tags:
- Cache
summary: Check if a key exists in cache
parameters:
- $ref: '#/components/parameters/CacheKey'
responses:
'200':
description: Whether the key exists.
content:
application/json:
schema:
type: boolean
/counters/{counter-name}/increment/get:
put:
operationId: incrementAndGet
tags:
- Counters
summary: Increment by 1 and return current
description: Atomically increments the counter by one and returns the new value.
parameters:
- $ref: '#/components/parameters/CounterName'
responses:
'200':
description: The current counter value after incrementing.
content:
application/json:
schema:
type: integer
format: int64
/counters/{counter-name}/incrementby/get:
put:
operationId: incrementByAndGet
tags:
- Counters
summary: Increment by N and return current
parameters:
- $ref: '#/components/parameters/CounterName'
- name: value
in: query
required: true
description: Amount to add to the counter.
schema:
type: integer
format: int64
responses:
'200':
description: The current counter value after incrementing.
content:
application/json:
schema:
type: integer
format: int64
/counters/{counter-name}/get:
get:
operationId: getCounter
tags:
- Counters
summary: Get the current counter value
parameters:
- $ref: '#/components/parameters/CounterName'
responses:
'200':
description: The current counter value.
content:
application/json:
schema:
type: integer
format: int64
/counters/{counter-name}/reset:
put:
operationId: resetCounter
tags:
- Counters
summary: Reset a counter to zero
parameters:
- $ref: '#/components/parameters/CounterName'
responses:
'200':
description: The counter was reset.
/services/{service-name}/{method-name}:
post:
operationId: invokeCloudCodeService
tags:
- CloudCode
summary: Invoke a custom Cloud Code service method
description: >-
Calls a method on a developer-defined serverless API service deployed to
Backendless Cloud Code. The request and response shapes are defined by the
custom service implementation.
parameters:
- name: service-name
in: path
required: true
schema:
type: string
- name: method-name
in: path
required: true
schema:
type: string
requestBody:
required: false
content:
application/json:
schema:
type: object
additionalProperties: true
responses:
'200':
description: The value returned by the custom service method.
content:
application/json:
schema:
type: object
additionalProperties: true
'400':
$ref: '#/components/responses/Error'
components:
securitySchemes:
userToken:
type: apiKey
in: header
name: user-token
description: >-
Session token returned by POST /users/login. Required on operations that
run in the context of an authenticated user. The application id and REST
API key that scope every request are carried in the server URL path rather
than as a security scheme.
parameters:
TableName:
name: table-name
in: path
required: true
description: Name of the database table (data store class).
schema:
type: string
ObjectId:
name: object-id
in: path
required: true
description: System-assigned objectId of a stored object.
schema:
type: string
CacheKey:
name: key
in: path
required: true
description: Cache entry key.
schema:
type: string
CounterName:
name: counter-name
in: path
required: true
description: Name of the atomic counter.
schema:
type: string
responses:
Error:
description: A Backendless error response.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
schemas:
DataObject:
type: object
description: A persisted object. Includes Backendless system properties.
properties:
objectId:
type: string
created:
type: integer
format: int64
updated:
type: integer
format: int64
ownerId:
type: string
___class:
type: string
additionalProperties: true
RegistrationRequest:
type: object
required:
- password
properties:
email:
type: string
password:
type: string
name:
type: string
additionalProperties: true
LoginRequest:
type: object
required:
- login
- password
properties:
login:
type: string
description: User identity value, typically the email address.
password:
type: string
User:
type: object
properties:
objectId:
type: string
email:
type: string
name:
type: string
user-token:
type: string
description: Session token for subsequent authenticated requests.
userStatus:
type: string
additionalProperties: true
FileInfo:
type: object
properties:
fileURL:
type: string
format: uri
PublishMessageRequest:
type: object
properties:
message:
description: Arbitrary message payload (string or object).
headers:
type: object
additionalProperties: true
publishAt:
type: integer
format: int64
pushPolicy:
type: string
enum: [ONLY, ALSO, NONE]
pushBroadcast:
type: integer
pushSinglecast:
type: array
items:
type: string
MessageStatus:
type: object
properties:
messageId:
type: string
status:
type: string
errorMessage:
type: string
EmailRequest:
type: object
required:
- subject
- to
properties:
subject:
type: string
to:
type: array
items:
type: string
bodyparts:
type: object
properties:
textmessage:
type: string
htmlmessage:
type: string
GeoPoint:
type: object
properties:
objectId:
type: string
latitude:
type: number
format: double
longitude:
type: number
format: double
categories:
type: array
items:
type: string
metadata:
type: object
additionalProperties: true
distance:
type: number
format: double
ErrorResponse:
type: object
properties:
code:
type: integer
description: Backendless error code (e.g. 3003 for invalid credentials).
message:
type: string