Starting Your First App

The REST API allows an app to interact with its backend on Kinvey programmatically over simple HTTP requests. These requests provide access to the entire core Kinvey functionality.

In designing this API, we have taken the pure REST principles as far as possible. For example, we present data entities as HTTP resources and the typical HTTP verb semantics apply, making accessing data very intuitive.

As with most web APIs, there is some amount of RPC-style REST calls which operate on existing resources, like a previously created user entity, and modify their state.

Add an App Backend

Start with signing up if you don't have an account with Kinvey yet.

In the Kinvey console, click Create an App and enter the name of your app when prompted.

Add an app in Console

You can find your key and secret in the dropdown menu in the environment sidebar.

Key and secret

Copy the key and secret when performing the next steps.

Call an Endpoint

The REST APIs use https://baas.kinvey.com as base URL to which you need to add the resource that you want to work with, your App Key, and, optionally, additional resources and parameters.

HTTP_VERB https://baas.kinvey.com/:resource/:appKey{/resource/specific/path}{?parameters}

Customers with dedicated Kinvey instances and Progress Health Cloud customers need to substitute their dedicated host URL for the base URL. Follow these instructions to assemble your dedicated host URL:

Go to the Kinvey Console and find your Instance ID on the dashboard. It is listed next to the App Key and App Secret.
Insert your Instance ID into the following URL template:

https://<Your Instance ID>-baas.kinvey.com

Unless noted otherwise, the HTTP verb changes the behavior of the endpoint. GET retrieves the entity, DELETE removes it, POST creates a new one based on the body passed, and PUT updates or creates depending on the presence of an _id.

For example, the following GET request retrieves a single entity from the Books collection by ID.

GET https://baas.kinvey.com/appdata/kid_HkI2u1vGZ/Books/3973ffa3e39aa697420dada0

If you call the same endpoint but with the PUT verb, it will look to update the specified entity with data passed as payload.

GET https://baas.kinvey.com/appdata/kid_HkI2u1vGZ/Books/3973ffa3e39aa697420dada0
Content-Type: application/json

<JSON-Document-representing-Entity>

Detailed information about the available endpoints is available in the corresponding guides.

Handshake

Making a GET to /appdata/:appKey/ is the easiest way to test connectivity to Kinvey.

GET /appdata/:appKey
Host: baas.kinvey.com
Authorization: [Basic Auth with app credentials]

HTTP/1.1 200 OK
Content-Type: application/json

{
  "version": "3.9",
  "kinvey": "hello Sample App",
  "appName": "Sample App",
  "environmentName": "Development"
}

This request is one of the few API calls that is authenticated with app credentials (using Basic Auth) and does not require a user context. (The other notable exception is POST /user/:appKey/ which creates a new user.)

The response contains the current version of Kinvey and the name of the app.

An authentication-less ping to Kinvey can also be performed by calling GET /appdata/:

GET /appdata/ HTTP/1.1
Host: baas.kinvey.com
Authorization: [Basic Auth with app credentials]

HTTP/1.1 200 OK
Content-Type: application/json

{
  "version": "3.9",
  "kinvey": "hello"
}

Required Headers

Authorization

Request Format

We use JSON as a data format throughout the service, both for input and output. An app must set the Content-Type HTTP header to application/json if and only if it's sending JSON in the request body,

Versioning

The Kinvey REST API is versioned. The goal of the versioning is to decouple a mobile app from any changes to the API, thus providing a seamless and uninterrupted experience for app users.

Any breaking changes that modify or change current behavior are released as part of a new version.

Kinvey assumes the latest API version but an app can force a specific API version by including the X-Kinvey-API-Version header in a request. The Kinvey backend will process the request using the version number specified in the header.

You need to take the following steps to upgrade to a new API version:

Implement the new functionality in the app
Change the value in the X-Kinvey-API-Version header included in requests to the new version
Make the new release of the app available for download

The X-Kinvey-API-Version header also makes it easy to test and debug code changes during development.

GET /appdata/:appKey/:collectionName/:id HTTP/1.1
Host: baas.kinvey.com
X-Kinvey-API-Version: 1
Authorization: Kinvey [auth token]

HTTP/1.1 200 OK
X-Kinvey-API-Version: 1
Content-Type: application/json

<JSON-Document-representing-Entity>

Versioning ensures that app users using an older revision of the app continue to receive service from Kinvey. At the same time, users who upgrade to the newly released revision are able to use new features.

Older versions of the Kinvey REST API will not be retired until well after all existing apps have upgraded and all app users have migrated to newer versions of apps.

The API version can also be configured through the Environment Settings page on the Kinvey Console. (The Console setting will expose all available API versions in a dropdown.) Doing so will automatically apply the configured version to requests that don't have a X-Kinvey-API-Version header. Configuring an API version through the Console makes it easier to release one-off short-lived apps, develop non-native apps, and use a push based mechanism for upgrades.

The API version actually applied by the Kinvey backend while processing a request is returned in a X-Kinvey-API-Version header included in the HTTP response.

Changelog

API version 6 introduces the following changes:

Multi-factor authentication support for end users.
Creating a new user through POST /user/:appKey/ does not automatically generate an auth token.
Basic authentication is no longer supported (except when using App or Master secret).

API version 5 introduces the following changes:

Adds Multi-insert support.

API version 4 introduces the following changes from API version 3:

If a query returns more than 10,000 entities, return a ResultSetSizeExceeded error instead of silently returning only the first 10,000.
The status code of OAuthTokenRefreshError has been changed from 500 to 401.
Files API changes:
- Support for resumable uploads has been added. See the Files guide for your SDK of choice for documentation.
- Including the X-Kinvey-Content-Type header is now mandatory when uploading.
- If a file does not exist, allow pre-hook Business Logic to execute on GET or DELETE instead of returning a 404 before any Business Logic is executed.

API version 3 introduces the following changes from API version 2:

New Files API.

API version 2 introduces the following changes from API version 1:

Data store deletes return a 200 OK response with a count of the number of entities in the response body instead of a 204 No Content.
A retrieve for a file returns a 200 OK with the CDN URI in the body of the response instead of a 302 Moved Temporarily response.
A user delete defaults to a soft delete (disable user account) instead of removal. An additional purge step is available for apps to secure all data access before purging a user from the backend.

API version 1 introduces the following changes from API version 0:

Standardized error reporting in response to bad requests.
Availability of session authentication.
Availability of on-demand user soft deletes that allows an app to disable users.

Security

The Authentication guide explains how requests are authenticated and the Access Control guide details how data access is authorized in the Kinvey backend.

Guides

Starting Your First App