API Basics

The RKStudio API is a REST-based interface, which means that applications make requests to the API by accessing specific URLs using HTTP. One of the hallmarks of REST is that the API calls are stateless, meaning each request is a single, self-contained operation.

Authentication

Every API call must contain an access token to authorize access to your project’s data. This will be sent in the HTTP header as a header key named “Authorization” containing the value “Bearer YOUR_TOKEN”. For more information on how to get an access token, see Authentication.

Required Headers

Every API call requires two fields in the HTTP request header:

Field Required Value Description
Authorization Bearer YOUR_TOKEN Contains the token that allows you to access the data. See Authentication for more information on how to obtain an access token.
Accept application/json Defines the data format the server should use. Only JSON is currently supported.

Data Formats

Data sent to and received from the RKStudio API will be in JSON format.

REST Basics

This section gives a brief introduction to REST APIs in general.

Resources

The URLs are centered around resources, which identify the kind of data you’re working with. For example, the URL api/v1/administration/projects/:projectId/participants is the URL for any API call that deals with project participants: querying them, adding them, updating them, and so on.

HTTP Verbs

Every API call uses a specific HTTP verb, which tells the system what kind of action you want to take with the resource. The verbs are summarized in the table below, but not all verbs apply to every resource. Consult the documentation for each resource to see what verbs are supported.

GET Gets data. This may be a query for all items matching a set of criteria, or a request for a specific item.
POST Submits data to the system, usually for adding a new item or taking a specific action with that item.
PUT Replaces an item with new data.
DELETE Deletes an item.

Segments

Some segments of the API URLs begin with a : to indicate that they are variables conveying information about the specific resource you wish to access. For example, the URL api/v1/administration/projects/:projectId/participants/:participantId identifies a resource with both a project ID and a participant ID.

Parameters

In addition to the segments, many API calls use query parameters and/or request body data to send data to the server.

Query parameters are usually found on GET requests, specifying the details of the query. For example, in a request for participants, you can add query parameters to control how the results are broken up into pages: api/v1/administration/projects/:projectId/participants?pageSize=1&pageNumber=2.

Body data is usually used in PUT and POST requests to pass along the specific resource data you wish to add/update. For example, in a POST request to api/v1/administration/projects/:projectId/participants, the body of the request would specify the details of the participant(s) you wanted to add.