Overview
Kinetise CMS (Content Management System) is a feature allowing to quickly setup and manage data for a mobile application built in Kinetise. Kinetise CMS allows to manage app users and any number of custom data tables which apps can read and write to. In Kinetise CMS you can use Standard endpoints to access and modify data from Kinetised application. Besides that, Kinetise CMS allows more advanced use cases as possibility to Import CSV files, define Custom endpoints, setup Cloud code and access CMS API.
Standard endpoints
Standard endpoints are automatically generated by Kinetise CMS for each data table and can be instantly used in Kinetise. Beside default functionality, standard endpoints provide a wide range of additional functionalities. This document describes these features.
General tables
Get feed
The URL to get a feed endpoint uses the following structure: https://api-cms.kinetise.com/api/kinetise/v2/projects/{projectId}/tables/{tableId}/rows/get-table.
By default, it returns all records from the table in the same order as they are visible in CMS GUI.
| Parameter name |
Parameter type |
Description |
| <exact_column_name> |
Params |
Filter rows by exact column value. Only these rows will be retrieved of which <exact_column_name> matches parameter value.
It is possible to filter relationship column values by passing a list of IDs, separated with a comma (example: relationship_column=1,2,3). The relationship to the Users table can additionally be filtered by the sessionId value (example: users_relationship_column=##GetSessionId##).
Example:
Let’s assume we have a news table with two columns: category and title.
| category |
title |
| economy |
Economy news title |
| sports |
Sports news title |
To download only items from the sports category, the URL should be formatted as follows:
/rows/get-table?category=sports
|
| _sort |
Params |
Sorts rows. The value of this parameter should be equal to the column name that sorting is based on. Let’s assume the following news table:
| order |
title |
| 2 |
Some news title |
| 1 |
Some other news title |
To sort news by order column values, the URL should be formatted as follows:
/rows/get-table?_sort=order
It is possible to sort rows in descending order by prefixing the column name with a minus (-) character:
/rows/get-table?_sort=-order
|
| _author |
Params |
Filter rows to contain only entries created by the currently logged in user. Value of the parameter must be a current session ID value (selectable in Kinetise Editor from "dynamic params" list).
/rows/get-table?_author=##GetSessionId##
|
| _search |
Params |
Filter rows to contain only entries for which any of the textual columns contains the search phrase provided as a value of the the parameter. Can be easily used with default settings of Search Widget.
/rows/get-table?_search=phrase
|
| _dropdown |
Params |
Serializes a relationship column to a Dropdown Widget-capable format. The value should be the name of the relationship-type column. Let’s assume we have the following tables:
news :
| value |
text |
| news_1 |
News one choice |
| news_2 |
News two choice |
news_dropdown :
| dropdown_choices |
| [2 related entries from News table] |
If the related entries come from a table with text and value columns, then the news_dropdown get-table feed can be used to initialize possible dropdown entries:
/rows/get-table?_dropdown=dropdown_choices
|
pageSize
pageStartID |
Params |
Returns a subset (page) of rows. Use to achieve data pagination.
pageSize specifies how many items are downloaded,pageStartID is the identifier of the last entry in the previous batch.
Let’s assume the following call was made:
/rows/get-table?pageSize=10&pageStartID=50
This would download a maximum of 10 entries with IDs greater than 50.
|
Create row
The URL to create row endpoint resembles the following: https://api-cms.kinetise.com/api/kinetise/v2/projects/{projectId}/tables/{tableId}/rows/create-row. Since it is used with a POST request, it can accept both query parameters and so-called body parameters, which are attached to the POST body.
| Parameter name |
Parameter type |
Description |
<exact_column_name>
latitude
longitude |
Body |
Each entry in the request Body will insert or update a value in the matching column. By default, request body contains values from all Form-type Widgets with keys (column names) equal to Form ID set in Kinetise Editor. It is possible to add more entries to the Body params to pass additional (not Form-originated) information.
Most common use case is to insert user's location along the data sent with the Form Widget. For this, a table needs to have latitude, longitude columns and Body params of the request should be expaned with parameters with the same name (selectable in Kinetise Editor from as "Gps" on the "dynamic params" list).
/rows/create-row
BODY:
{
"form" : {
"title":"Title 1"
},
"params" : {
"latitude":"##GetGpsLatitude##",
"longitude":"##GetGpsLongitude##"
}
}
|
| <sessionId> |
Params |
Sets a row’s author (created by) field to the currently logged in Kinetise user. Value of the parameter must be a current session ID value (selectable in Kinetise Editor from "dynamic params" list).
/rows/create-row?sessionId=##GetSessionId##
|
Users endpoints
List users
The URL to get feed endpoint resembles the following: https://api-cms.kinetise.com/api/kinetise/v2/projects/{projectId}/users/get-users.
| Parameter name |
Parameter type |
Description |
pageSize
pageStartID |
Params |
Returns a subset (page) of rows. Works same as for General Tables Get Feed endpoint.
|
| sessionId |
Params |
Download details of the currently logged-in user. Value of the parameter must be a current session ID value (selectable in Kinetise Editor from "dynamic params" list).
/users/get-users?sessionId=##GetSessionId##
|
Importing CSV files
Kinetise CMS can import CSV files in a special format. It describes not only data, but also data structure. CSV exported from an empty table can be used as a reference.
To be imported into Kinetise CMS CSV file has to:
- Use
; character as a delimiter. Currently we don’t support other delimiters.
- First row has to describe data structure (Kinetise CMS columns). Every column has to be described with four parameters:
- name of a column,
- type of a column (see Data types section),
- default value of a column (or
0 if none),
- column requirement indicator (
0 if required or 1 if not).
- Every data row has to be in correct format:
text - simple string.number - simple string.boolean - either 0 string (false) or 1 string (true).datetime - has to be in yyyy-MM-dd hh:mm:ss format (GMT timezone). (Default value for date columns is specified in RFC 822 format).image - is a Base64 encoded image.relation - is in ${tableName} ${relatedRowsArray} format. Example: related [1,2,3].
Custom endpoints
Custom endpoints allow to modify data structure before it is processed by Kinetise CMS endpoints. To understand how custom endpoints work you will need to have a little knowledge about how Kinetise exposes and receives data.
Usage
To use a custom endpoint you have to:
- Create a custom endpoint entry in Custom code > Customize endpoints.
- Specify a transformation for this endpoint (explained below). You can do that in a modal window that pops up after clicking a button in Transformation column.
- Copy endpoint URL by clicking on a button in Endpoint URL column.
- Paste this endpoint into corresponding list / form URL in Kinetise app (instead of an original one).
Kinetise uses JSON format to expose and receive data. You can use JQ format to define transformation to be applied over default JSON format generated by CMS.
Transformation in different endpoint types
get-table
For get-table transformation is applied after endpoint returns its value. Assume that a get-table endpoint returns following data:
{
"results": [{
"id": "2",
"title": "This is a basic list displaying texts and images.",
"description": "It contains data from the Kinetise backend\/CMS.",
"_created_ts": "2016-07-19T20:57:35+02:00",
"_updated_ts": "2016-07-19T20:57:35+02:00"
},
{
"id": "3",
"title": "To open CMS, click the CMS tab on the left of the screen.",
"description": "CMS is a powerful tool, but let\u0027s focus on getting data now.",
"_created_ts": "2016-07-19T20:57:35+02:00",
"_updated_ts": "2016-07-19T20:57:35+02:00"
}]
}
To count how many items are in this feed you could use transformation presented below:
{ "sample_items_count" : .results | length }
This transformation would be applied to an original feed. As a result following JSON would be returned to Kinetise:
{"sample_items_count":2}
create-row, update-row, delete-row
create-row transformation is applied before the data is put into an original endpoint. Assume that there is a list inside your form and Kinetise sends data in the following format:
{
"form": {
"list": [
{
"id": 1,
"selected": true
},
{
"id": 2,
"selected": false
},
{
"id": 3,
"selected": true
}
]
},
"params": {
}
}
Assume that you want to create a single new row with relationship column (called relation) set to selected elements. For that task you could use following JQ transformation:
{
"form": {
"relation": (.form.list | map(select(.selected == true)) | map(.id))
},
"params": {
}
}
Applied to input JSON this transformation would produce following output:
{
"form": {
"relation": [
1,
3
]
},
"params": {
}
}
which is transferred to create-row endpoint and correctly interpreted by Kinetise CMS as a relationship value.
Cloud Code
Cloud Code enables developers to extend CMS functionality with arbitrary logic. It acts as a web-hook layer for all Kinetise endpoints.
Basic concept
Every time Kinetise CMS endpoint is called cloud code web-hook is invoked to either:
- Alter how the data is formatted when fetched from / inserted into a table. Those web-hooks should return response which later alters Kinetise CMS endpoints’ behavior.
- Notify about a data change event. Those web-hooks’ response does not modify Kinetise CMS endpoint’s behavior.
Examples:
- Assume invitation e-mail should be send every time an invitation is created in Kinetise CMS. Second type of web-hook should be used, because it does not alter the way invitation is stored inside Kinetise CMS.
- Assume a tax has to be added to an order every time an order is placed. First type of web-hook should be used, because it has to modify the data that is going to be stored inside Kinetise CMS.
For the rest of this document the first type will be referred to as hooks, while the second one as triggers.
Web-hook method description
Request
Both web-hook types should handle POST requests with following JSON body:
{
"projectGuid": "${projectIdentifier}",
"table": "${tableName}",
"originalRequest": {
"params": {
"${parameterOneName}": "${parameterOneValue}",
"${parameterTwoName}": "${parameterTwoValue}"
},
"headers": {
"${headerOneName}": "${headerOneValue}",
"${headerTwoName}": "${headerTwoValue}"
},
"body": {
"${firstBodyPropertyName}": "${firstBodyPropertyValue}",
"${secondBodyPropertyName}": "${secondBodyPropertyValue}"
}
},
"data": {
"columns": {
"${firstColumnName}": "${firstColumnType}",
"${secondColumnName}": "${secondColumnType}"
},
"rows": [
{
"${firstRowFirstColumnName}": "${firstRowFirstColumnValue}",
"${firstRowSecondColumnName}": "${firstRowSecondColumnValue}"
},
{
"${secondRowFirstColumnName}": "${secondRowFirstColumnValue}",
"${secondRowSecondColumnName}": "${secondRowSecondColumnValue}"
}
]
}
}
where:
projectGuid describes project identifier,table describes name of a table in behalf of which an endpoint was originally invoked,originalRequest describes properties of a request send to Kinetise CMS:
parameters is a dictionary of query parameters passed in request’s URL,headers is a dictionary of headers passed in request,body is a copy of body passed to a request (present only for POST requests),
data describes rows and columns of originally requested data:
columns contain pairs of column names and column types,rows is an array with descriptions of every item connected to original request.
Response
Status codes
2xx HTTP success status code should be returned to indicate that web-hook completed successfully. Any 4xx or 5xx HTTP error status code will make original Kinetise CMS fail.
Response body
In case of triggers request body is not checked. Any hook should respond with body in following format:
{
"columns": {
"${firstColumnName}": "${firstColumnType}",
"${secondColumnName}": "${secondColumnType}"
},
"rows": [
{
"${firstRowFirstColumnName}": "${firstRowFirstColumnValue}",
"${firstRowSecondColumnName}": "${firstRowSecondColumnValue}"
},
{
"${secondRowFirstColumnName}": "${secondRowFirstColumnValue}",
"${secondRowSecondColumnName}": "${secondRowSecondColumnValue}"
}
]
}
where:
columns describes returned data scheme,rows describes actual returned data.
Cloud Code types
Hooks
User
| No. |
Endpoint |
Hook type |
Description |
| 1. |
alterapi |
pre_register |
It is invoked before user registration is completed with AlterAPI form. It receives details of a freshly registered user and expects to get formatted data of this user back. |
| 2. |
facebook |
pre_register |
It is invoked before first Facebook login for a user is completed. Works the same as the pre_register one for alterapi. |
| 3. |
linkedin |
pre_register |
It is invoked before first LinkedIn login for a user is completed. Works the same as the pre_register one for alterapi. |
| 4. |
get-users |
format_data |
It is invoked before data is converted to Kinetise format for get-users endpoint. It receives list of user details fetched from Kinetise CMS database and expects to get a formatted list of users back. |
Data table
| No. |
Endpoint |
Hook type |
Description |
| 1. |
get-table |
format_data |
It is invoked before data is converted to Kinetise format for get-table endpoint. It receives list of table rows fetched from Kinetise CMS database and expects to get a formatted list of rows back. |
| 2. |
create-row |
pre_create |
It is invoked before data of a new entry is inserted into Kinetise CMS database in create-row endpoint. It receives list of table rows to insert and expects to get a formatted list of rows back. |
| 3. |
update-row |
pre_update |
It is invoked before updated data of existing entry is inserted into Kinetise CMS database in update-row endpoint. It receives list of table rows to insert and expects to get a formatted list of rows back. |
Triggers
User
| No. |
Endpoint |
Hook type |
Description |
| 1. |
alterapi |
post_login |
It is invoked after user has logged in using AlterAPI login. It receives details of a logged in user. |
| 2. |
alterapi |
post_register |
It is invoked after user has registered using AlterAPI register endpoint. It receives details of a newly registered user. |
| 3. |
alterapi |
post_logout |
It is invoked after user has logged out using AlterAPI logout endpoint. It receives details of a logged out user. |
| 4. |
facebook |
post_login |
It is invoked after user has logged in using Facebook login. It receives details of a logged in user. |
| 5. |
linkedin |
post_login |
It is invoked after user has logged in using LinkedIn login. It receives details of a logged in user. |
Data table
| No. |
Endpoint |
Hook type |
Description |
| 1. |
get-table |
data_requested |
It is invoked after data is requested for get-table endpoint. It receives list of table rows that were returned to a user. |
| 2. |
create-row |
post_create |
It is invoked after data is inserted into Kinetise CMS database for create-row endpoint. It receives list of inserted table rows. |
| 3. |
update-row |
post_update |
It is invoked after data is updated in Kinetise CMS database for update-row endpoint. It receives list of updated table rows. |
| 4. |
delete-row |
post_delete |
It is invoked after data is deleted from Kinetise CMS database for delete-row endpoint. It receives list of removed table rows. |
Bi-directional communication
In some scenarios the data received as an input for a web-hook might not be enough:
- Some details about a user that inserted a data row are needed.
- Some related data in other data table have to be updated alongside the original table.
In such cases a web-hook can use CMS Developer API to fetch or alter data (or data scheme) for a project. CMS Developer API exposes a set of methods used by Kinetise CMS system in order to manage CMS project.
CMS Developer API
CMS Developer API is a set of RESTful services which allow to integrate with Kinetise CMS. It allows to perform per-project operations such as:
- Creating tables,
- Inserting table’s data,
- Listing users.
To use CMS Developer API you need to obtain two things:
- project identifier,
- valid access token.
Project identifier
To obtain a project identifier:
- Go to Data tab in Kinetise Editor.
- Select Custom code from hamburger menu.
- Click on API key management tile.
- Project identifier will be presented in an alert box.
You can copy this identifier to clipboard using a copy button located next to the identifier.
Authentication
Every call made to CMS Developer API has to provide a valid access_token for a given project. To obtain such a token:
- Go to Data tab in Kinetise Editor.
- Select Custom code from hamburger menu.
- Click on API key management tile.
- Specify a symbolic name for an app that uses the API in Application name field.
- Press Add button.
Token will be presented to you. Make sure to store this token securely, cause there is no way to retrieve it later.
Retrieved token has to be appended as an access_token query parameter to every API call.
Example: assuming your generated token is equal to XYZ a valid API call to get users list for project with abc identifier would be:
https://api-cms.kinetise.com/api/kinetise/v1/projects/abc/users?access_token=XYZ
API Reference
The API defines following entity types:
- Project is a single CMS application that is created for every Kinetise app.
- Table is a single data table from CMS. Tables are listed in hamburger menu under Data section.
- Column is a single data column that belongs to a data table in CMS. Columns are listed in table’s view.
- Row is a single data entry in a data table in CMS. Rows are also listed in table’s view.
API reference conventions
Every URL presented below follows four conventions:
- It is a relative URL. Mutual host for all CMS Developer API methods is located under
https://api-cms.kinetise.com.
- It contains
{apiVersion} string which has to be replaced with an api version code. This reference describes API version 1. It is identified by v1 code.
- It contains
{projectIdentifier} string which has to be replaced with project identifier. See section Project identifier for more details.
- It requires authentication parameter to be passed. See Authentication section for more details.
It means that an API method referenced to as:
/api/kinetise/{apiVersion}/projects/{projectIdentifier}/users
for a project with identifier abc secured by token XYZ can be invoked like this:
https://api-cms.kinetise.com/api/kinetise/v1/projects/abc/users?access_token=XYZ
Data types
CMS Developer API is a REST API. All requests should contain Content-Type header set to application/json. Depending on a column type data should be sent in appropriate format:
| No. |
Column type |
API data format |
Example |
| 1. |
text |
JSON string |
{ "text": "Example text" } |
| 2. |
float |
JSON decimal/float |
{ "float": 2.12 } |
| 3. |
boolean |
JSON boolean |
{ "boolean": true } |
| 4. |
datetime |
Date in RFC 3339 format as JSON string |
{ "date": "2016-02-10T12:24:30+01:00" } |
| 5. |
image |
Base64 encoded image as JSON string |
{ "image": "iVB(...)5CYII=" } |
| 6. |
relation |
JSON array of object IDs |
{ "relation": [ "1", "2" ] } |
Columns
Configuration options
CMS Developer API exposes a variety of column types to work with. Every column has following configuration options:
name - a name of a column.type - a type of a column.subtype - specifies full column type together with type (where applicable).default_value - specifies a default value for a column (a format depends on a column type and is described in Data types section).is_required - specifies whether a column value is mandatory when creating a row from Kinetise endpoint.related_table - specifies an identifier of related table (if applicable). Example: { "related_table": "1" } where 1 is table identifier (see id field in Listing tables section).base_columns - specifies an identifier of base columns for a column to work on (if applicable). Example: { "base_columns": ["1", "2"] } where 1 and 2 are column identifiers (see id field in Listing columns section).parameters - specifies additional configuration parameters for a column (if applicable).
Column types
Following column types are available:
| No. |
Column type |
Description |
| 1. |
text |
Column of text type. Cannot have any of subtype, related_table, base_columns or parameters set. |
| 2. |
float |
Column of a number type. Cannot have any of subtype, related_table, base_columns or parameters set. |
| 3. |
boolean |
Column of a boolean type. Cannot have any of subtype, related_table, base_columns or parameters set. |
| 4. |
datetime |
Column of a datetime type. Cannot have any of subtype, related_table, base_columns or parameters set. |
| 5. |
image |
Column of a image type. Cannot have any of subtype, related_table, base_columns or parameters set. |
| 6. |
relation |
Column of a relationship type. Have to have a single related_table defined. Cannot have any of subtype, base_columns or parameters set. |
| 7. |
virtual |
Generic column type which represents a column that is not physically stored in Kinetise CMS. Cannot have related_table defined. Has to have subtype defined. May have base_columns and parameters defined. |
Virtual column subtypes
| No. |
Virtual column type |
Description |
| 1. |
count_related |
Returns a count of elements in a relationship. Has to have exactly one base column defined (of relation type). Does not take any parameters. |
| 2. |
get_first_related |
Includes values of all columns from a first related row to the parent row. All included columns are prefixed with virtual column name. Has to have exactly one base column defined (of relation type). Does not take any parameters. |
| 3. |
get_last_related |
Works exactly like get_first_related, but takes last element instead of the first. |
| 4. |
get_related_field |
Operates on a relationship. Returns a list of all values for a given column separated by comas. Has to have exactly one base column defined (of relation type). Takes a single parameter related_field which is a name of a column to join values from. |
| 5. |
format_string |
Operates on one or more non-relationship, non-image type columns. Returns a text where all occurrences of {columnName} are replaced with {columnName} value. Has to have one or more base column defined. Takes a single parameter string_format with a format to return. |
Working with tables
Listing tables
GET /api/kinetise/{apiVersion}/projects/{projectIdentifier}/tables
API will respond with a list of all tables. Example:
[
{
"id": "1",
"name": "sample",
"tableGUID": "fdc445863226550411fdc2b5"
},
{
"id": "2",
"name": "sample_offline",
"tableGUID": "14174b163c7e4ef9586e6711"
}
]
where:
id - is a table identifier,name - is a table name,tableGUID - is a deprecated table identifier string.
Creating a table
POST /api/kinetise/{apiVersion}/projects/{projectIdentifier}/tables
The request should have a following body:
[
{
"name": "${newTableName}"
}
]
where ${newTableName} is a name of a table to create. You can create multiple tables in single request. The API will respond with newly created tables’ data. Example:
[
{
"table_id": "4",
"tableGUID": "a35c084ef0fe052a92b165e5",
"name": "new_table"
}
]
where:
table_id - is a table identifier,name - is a table name,tableGUID - is a deprecated table identifier string.
Updating a table
PUT /api/kinetise/{apiVersion}/projects/{projectIdentifier}/tables/{tableIdentifier}
where {tableIdentifier} is a table identifier that you can obtain from a table list (see id field in Listing tables section). The request should have a following body:
{
"name": "${tableNameAfterRename}"
}
where ${tableNameAfterRename} is a name of a table to rename it to. The API will respond with renamed table data. Example:
{
"table_id": "1",
"name": "renamed_table"
}
where:
table_id - is a table identifier,name - is a table name after rename.
Deleting a table
DELETE /api/kinetise/{apiVersion}/projects/{projectIdentifier}/tables/{tableIdentifier}
where {tableIdentifier} is a table identifier that you can obtain from a table list (see id field in Listing tables section).
The API will respond with an empty body:
{}
Working with data inside tables
Listing data rows
GET /api/kinetise/{apiVersion}/projects/{projectIdentifier}/tables/{tableIdentifier}/rows
where {tableIdentifier} is a table identifier that you can obtain from a table list (see id field in Listing tables section).
API will respond with a list of all table’s rows. Example:
[
{
"id": "1",
"title": "This is a basic list displaying texts and images.",
"description": "It contains data coming from Kinetise backend/CMS.",
"image": "https://api-cms.kinetise.com/api/kinetise/v1/projects/ae368da5aa29de5789bfcd24f89b657b/tables/1/columns/3/rows/2?ts=3d49698b3028ada0b540a02593a203f5",
"_created_ts": "2016-02-10T12:24:30+01:00",
"_updated_ts": "2016-02-10T12:24:30+01:00",
"_author_id": null,
"_author_username": null,
"_author_email": null,
"_author_role_name": null,
"_author_first_name": null,
"_author_last_name": null,
"_author_picture": null
},
{
"id": "2",
"title": "To open CMS, click pink DATA tab on the left of the screen.",
"description": "CMS is a powerful tool, but let's focus on getting data now.",
"image": "https://api-cms.kinetise.com/api/kinetise/v1/projects/ae368da5aa29de5789bfcd24f89b657b/tables/1/columns/3/rows/3?ts=3d49698b3028ada0b540a02593a203f5",
"_created_ts": "2016-02-10T12:24:30+01:00",
"_updated_ts": "2016-02-10T12:24:30+01:00",
"_author_id": null,
"_author_username": null,
"_author_email": null,
"_author_role_name": null,
"_author_first_name": null,
"_author_last_name": null,
"_author_picture": null
}
]
where:
id - is an identifier of a row,_created_ts - is a timestamp of record creation in RFC 3339 format,_update_ts - is a timestamp of last record update in RFC 3339 format,_author_${property} - describes a creator of the row (if the row was created from Kinetise app),- all other properties are data column values for a row.
Creating a data row
POST /api/kinetise/{apiVersion}/projects/{projectIdentifier}/tables/{tableIdentifier}/rows
where {tableIdentifier} is a table identifier that you can obtain from a table list (see id field in Listing tables section).
The request body should describe inserted data. Every key should be a name of existing data column. Every value should be value for this column. Value format depends on column type and is described in Data types section. Example request:
{
"title": "New row title",
"description": "New row description"
}
The API will respond with newly created row’s data. Example:
{
"id": "8",
"title": "New row title",
"description": "New row description",
"image": null,
"_created_ts": "2016-02-10T13:55:43+01:00",
"_updated_ts": "2016-02-10T13:55:43+01:00",
"_author_id": null,
"_author_username": null,
"_author_email": null,
"_author_role_name": null,
"_author_first_name": null,
"_author_last_name": null,
"_author_picture": null
}
where:
id - is an identifier of a row,_created_ts - is a timestamp of record creation in RFC 3339 format,_update_ts - is a timestamp of last record update in RFC 3339 format,_author_${property} - describes a creator of the row (if the row was created from Kinetise app),- all other properties are data column values for a row.
Updating a data row
PUT /api/kinetise/{apiVersion}/projects/{projectIdentifier}/tables/{tableIdentifier}/rows/{rowIdentifier}
where:
{tableIdentifier} is a table identifier that you can obtain from a table list (see id field in Listing tables section),{rowIdentifier} is a data row identifier that you can obtain from a row list (seeid` field in Listing data rows section).
The request body should describe inserted data. Every key should be a name of existing data column. Every value should be value for this column. Value format depends on column type and is described in Data types section. Example request:
{
"title": "Updated row title"
}
The API will respond with freshly updated row’s data. Example:
{
"id": "1",
"title": "Updated row title",
"description": "Not updated row description",
"image": null,
"_created_ts": "2016-02-10T13:55:43+01:00",
"_updated_ts": "2016-02-10T13:55:43+01:00",
"_author_id": null,
"_author_username": null,
"_author_email": null,
"_author_role_name": null,
"_author_first_name": null,
"_author_last_name": null,
"_author_picture": null
}
where:
id - is an identifier of a row,_created_ts - is a timestamp of record creation in RFC 3339 format,_update_ts - is a timestamp of last record update in RFC 3339 format,_author_${property} - describes a creator of the row (if the row was created from Kinetise app),- all other properties are data column values for a row.
Deleting a data row
DELETE /api/kinetise/{apiVersion}/projects/{projectIdentifier}/tables/{tableIdentifier}/rows/{rowIdentifier}
where:
{tableIdentifier} is a table identifier that you can obtain from a table list (see id field in Listing tables section),{rowIdentifier} is a data row identifier that you can obtain from a row list (seeid` field in Listing data rows section).
The API will respond with an empty body:
{}
Batch deleting data rows
POST /api/kinetise/{apiVersion}/projects/{projectIdentifier}/tables/{tableIdentifier}/rows/batch-delete
where {tableIdentifier} is a table identifier that you can obtain from a table list (see id field in Listing tables section).
The request body should contain row identifiers of rows to delete. You can obtain those identifiers from a row list (see id field in Listing data rows section). Example request body to delete rows with identifiers of 3 and 4:
{
"ids": ["3", "4"]
}
The API will respond with an empty body:
{}
Working with columns inside tables
Listing columns
GET /api/kinetise/{apiVersion}/projects/{projectIdentifier}/tables/{tableIdentifier}/columns
where {tableIdentifier} is a table identifier that you can obtain from a table list (see id field in Listing tables section).
API will respond with a list of all table’s columns. Example:
[
{
"id": "1",
"table_id": "1",
"name": "title",
"type": "text",
"subtype": null,
"default_value": null,
"is_required": "0"
},
{
"id": "2",
"table_id": "1",
"name": "description",
"type": "text",
"subtype": null,
"default_value": null,
"is_required": "0"
},
{
"id": "3",
"table_id": "1",
"name": "image",
"type": "image",
"subtype": null,
"default_value": null,
"is_required": "0"
},
{
"id": "4",
"table_id": "1",
"name": "_created_ts",
"type": "datetime",
"subtype": null,
"default_value": null,
"is_required": "0"
},
{
"id": "5",
"table_id": "1",
"name": "_updated_ts",
"type": "datetime",
"subtype": null,
"default_value": null,
"is_required": "0"
}
]
where:
id - identifier of a column,table_id - identifier of a table containing this column (see id field in Listing tables section),- other fields are described in Columns’ Configuration Options section.
Creating a column
POST /api/kinetise/{apiVersion}/projects/{projectIdentifier}/tables/{tableIdentifier}/columns
where {tableIdentifier} is a table identifier that you can obtain from a table list (see id field in Listing tables section).
The request body should describe inserted column. Configuration is described in details in Columns’ Configuration Options section. Example request:
[
{
"table_id": "1",
"name": "new_text_column",
"type": "text",
"subtype": null,
"default_value": null,
"is_required": false
}
]
where:
table_id - identifier of a table containing this column (see id field in Listing tables section),name - name of the new column,- other options are described in detail in Columns’ Configuration Options section.
The API will respond with an empty body:
{}
Updating a column
PUT /api/kinetise/{apiVersion}/projects/{projectIdentifier}/tables/{tableIdentifier}/columns/{columnIdentifier}
where:
{tableIdentifier} is a table identifier that you can obtain from a table list (see id field in Listing tables section),{columnIdentifier} is a column identifier that you can obtain from a column list (see id field in Listing columns section).
The request body should describe inserted column. Configuration is described in details in Columns’ Configuration Options section. Please note that not all column update operations are valid. We support only operations listed below:
- setting a new name,
- changing a default value,
- changing
is_required property value,
- changing virtual column’s
subtype, base_columns and parameters.
{
"name": "updated_column_name"
}
The API will respond with an empty body:
{}
Deleting a column
DELETE /api/kinetise/{apiVersion}/projects/{projectIdentifier}/tables/{tableIdentifier}/columns/{columnIdentifier}
where:
{tableIdentifier} is a table identifier that you can obtain from a table list (see id field in Listing tables section),{columnIdentifier} is a column identifier that you can obtain from a column list (see id field in Listing columns section).
The API will respond with an empty body:
{}
Working with users
Listing users
GET /api/kinetise/{apiVersion}/projects/{projectIdentifier}/users
The API will respond with a list of users. Example:
[
{
"id": "1",
"username": "kinetise_cms_user",
"email": "cmsuser@kinetise.com",
"created": "2016-02-11 11:13:38",
"first_seen": null,
"last_login": null,
"total_logins": "1",
"user_role": "USER",
"_is_deleted": false,
"devices": [],
"social": {
"Kinetise": {
"service_id": null,
"first_name": "Kinetise",
"last_name": "CMS User",
"country": null,
"city": "Warsaw",
"picture": null,
"profile_url": null
}
},
"first_name": "Kinetise",
"last_name": "CMS User",
"picture": null,
"city": "Warsaw",
"country": null
}
]
where:
* id - user identifier.
* social - describes social channel data for user. Currently three social sources are supported: Kinetise, facebook and linkedin. Kinetise is a CMS social entry, is initially populated with other sources (if possible) and always exists. facebook and linkedin socials exists only if user logged in with appropriate provider.
* devices - stores info about mobile devices that user used to log in.
* Other fields are actual user data.
Fetching single user details
GET /api/kinetise/{apiVersion}/projects/{projectIdentifier}/users/{userIdentifier}
where {userIdentifier} is a user identifier that you can obtain from a user list (see id field in Listing users section).
The API will respond with single user data. Example:
{
"id": "1",
"username": "kinetise_cms_user",
"email": "cmsuser@kinetise.com",
"created": "2016-02-11 11:13:38",
"first_seen": null,
"last_login": null,
"total_logins": "1",
"user_role": "USER",
"_is_deleted": false,
"devices": [],
"social": {
"Kinetise": {
"service_id": null,
"first_name": "Kinetise",
"last_name": "CMS User",
"country": null,
"city": "Warsaw",
"picture": null,
"profile_url": null
}
},
"first_name": "Kinetise",
"last_name": "CMS User",
"picture": null,
"city": "Warsaw",
"country": null
}
where fields are exactly the same as described in Listing users section.
Creating user
POST /api/kinetise/{apiVersion}/projects/{projectIdentifier}/users
The request body should describe user. Currently, we support following parameters:
username - required field with username.password - required field with password. It has to be pre-hashed with SHA1 algorithm.user_role - identifier of a user role (see Listing user roles). If not present, default is set.first_name - first name for Kinetise social channel.last_name - last name for Kinetise social channel.city - city for Kinetise social channel.
Example request body:
{
"username": "new_user",
"password": "5baa61e4c9b93f3f0682250b6cf8331b7ee68fd8",
"first_name": "New",
"second_name": "User"
}
The API will respond with created user details. Example API response:
{
"id": "2",
"username": "new_user",
"created": "2016-02-11 12:27:01",
"social": {
"Kinetise": {
"service_id": null,
"first_name": "New",
"last_name": null,
"country": null,
"city": null,
"picture": null,
"profile_url": null
}
}
}
Updating user
PUT /api/kinetise/{apiVersion}/projects/{projectIdentifier}/users/{userIdentifier}
where {userIdentifier} is a user identifier that you can obtain from a user list (see id field in Listing users section).
The request body should describe user. Currently, we support updating following parameters:
username - symbolic username.password - user password. It has to be pre-hashed with SHA1 algorithm.user_role - identifier of a user role (see Listing user roles).email - e-mail address of a user.
Updating user social info
PUT /api/kinetise/{apiVersion}/projects/{projectIdentifier}/users/{userIdentifier}/add-info
where {userIdentifier} is a user identifier that you can obtain from a user list (see id field in Listing users section).
The request body should describe user social info. Currently, we support updating following parameters:
first_name - user’s first name.last_name - user’s last name.city - user’s location.picture - user’s picture. It has to be send as Base64 encoded image (see image type under Data types).
Batch delete users
POST /api/kinetise/{apiVersion}/projects/{projectIdentifier}/users/delete
Request body have to specify a list of users to delete under ids entry (see id field under Listing users section). Example body:
{
"ids": ["2"]
}
The API will respond with an empty body:
{}
Listing user roles
GET /api/kinetise/{apiVersion}/projects/{projectIdentifier}/users/roles
The API will respond with a list of user roles. Example:
[
{
"id": "1",
"name": "USER",
"description": "Default role",
"is_default": true
}
]
where:
id - is a user role identifier,name - is a name of a user role,description - describes the role,is_default - specifies whether the role is a default one. At one moment there has to be one and only one role that has is_default set to true.
Creating user role
POST /api/kinetise/{apiVersion}/projects/{projectIdentifier}/users/roles
Request body has to describe user role. Currently we support following settings:
name - name of a role,description - description of a role,is_default - specifies whether the role is default. Important: if you create a default user role then all other roles will be marked non default.
Example request:
{
"name": "NEW_USER_ROLE",
"description": "New user role",
"is_default": false
}
The API will respond with an empty body:
{}
Updating user role
POST /api/kinetise/{apiVersion}/projects/{projectIdentifier}/users/roles/{roleIdentifier}
where {roleIdentifier} is an identifier of a role (see id field in Listing user roles).
Request body has to describe user role. We support the same settings as for creating user roles (see Creating user role section). Important: updating a default role to a non-default will always fail (cause there will be no default role), while setting a role to be default will result in setting other roles to non-default.
Example request body:
{
"is_default": true
}
The API will respond with an empty body:
{}
Batch deleting user roles
POST /api/kinetise/{apiVersion}/projects/{projectIdentifier}/users/roles/delete
Request body have to specify a list of user roles to delete under ids entry (see id field under Listing user roles section). Example body:
{
"ids": ["2"]
}
The API will respond with an empty body:
{}
Important: deleting roles will fail if you try to delete a default role (there has to be a default role defined).
Custom attributes
Users are a special case of data tables in Kinetise CMS. This module actually consists of a few data tables, but is presented as a single view.
The above fact has some implications in API. The most notable one is that custom user attributes are exposed as a data table with a special textual ID: _user_attributes.
In order to work with user attributes you can use all the data rows & columns methods replacing {tableIdentifier} with _user_attributes. For example to list _user_attributes for all users you would invoke:
GET /api/kinetise/{apiVersion}/projects/{projectIdentifier}/tables/_user_attributes/rows
The id values for _user_attributes always match id values of users.
