Getting Started

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

If you don't have an account on Kinvey yet, please signup before continuing.

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}

For Dedicated Kinvey customers, substitute your dedicated host URL for the base URL. You can find the host URL on the dashboard of the console, next to your App Key and App Secret.

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": "2.7",
  "kinvey": "hello Sample App"
}

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": "2.7",
  "kinvey": "hello Sample App"
}

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.

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.

The following steps should be implemented 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 1 introduced the following changes from API version 0:

API version 2 introduce 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 (disables users) instead of removal. An additional purge step is available for apps to secure all data access before purging a user from the backend.

Security

The Security guide has details on how requests are authenticated and data access is authorized in the Kinvey backend.

Got a question?