Getting Started

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

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.

Main Endpoints

Some of the main endpoints are below. Detailed information is available in the corresponding guides.

Use https://baas.kinvey.com as the host endpoint for accessing all REST APIs.

For Dedicated Kinvey customers, you'll need to use the endpoint for your dedicated host. You can find this host URL on the dashboard of the console, next to your App Key and App Secret.

Datastore

EndpointVerb(s)Description
/appdata/:appkeyGETSimple app handshake
/appdata/:appkey/:collectionName/:idGET, PUT, POST, DELETEMain resource CRUD
/appdata/:appkey/:collectionName/?query=...GETQuerying

Users

EndpointVerb(s)Description
/user/:appkey/:idGET, PUT, POST, DELETEMain user resource CRUD
/user/:appkey/loginPOSTValidate user credentials
/group/:appkey/:idGET, PUT, POST, DELETEUser Groups CRUD

Files

EndpointVerb(s)Description
/blob/:appkey/download-loc/:fileNameGETGets a URL to download the file from
/blob/:appkey/upload-loc/:fileNameGETGets a URL to upload the file to
/blob/:appkey/remove-loc/:fileNameGETGets a URL to delete the file at

RESTful

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. Specifically, 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.

As most web APIs, there is some amount of RPC-style REST calls. Examples of that is the User login method above. They operate on existing resources, like a previously created user entity, and modify its state.

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?