Labels API

Obtaining the User API token

In order to be able to use Labels API you must have an individual User API token, which can be found in space settings in devtodev system.

You will be able to see the interface unit with User API token in space settings only in case your price plan and access rights (role) allow you to use devtodev API. You can discard User API token or create it again on the same page.

Pay your attention that if you use several spaces, each of them will have an individual User API token.

Obtaining the list of categories

The result of the request is the obtaining of the list of all existing labels categories for the app.

Request:

https://www.devtodev.com/api/v1/labels/categories/get

POST

{
	"user_token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", // devtodev user API token
	"app_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"  // devtodev App ID
}

Response:

{
	"status_code": 200,
	"data": {
		"status": "complete",
		"categories": [
			"category name",
			"category name 2"
		]
	}
}

Removing categories

The request is used to remove or rename a category. The category can be removed only if its full name is specified. One request can remove only one category. In case the parameter move_labels_to_category is specified, labels that belong to the category that is going to be removed will be transfered to the specified category. If the specified category doesn't exist, it will be created. If move_labels_to_category is not specified, all the labels that belong to the category will be removed.

Request:

https://www.devtodev.com/api/v1/labels/categories/delete

POST

{
	"user_token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
	"app_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
	"category": "category to be removed",
	"move_labels_to_category": "category to which the labels will be moved"
}

Response:

{
	"status_code": 200,
	"data": {
		"status": "deleted",
		"category": "category to be removed"
	}
}

Obtaining the list of labels

The result of the request is the obtaining of the list of labels that are presented as objects.

You can use filters to get some specific labels you need. In case no filter is specified, you will receive the whole list of labels. It is possible to use any combination of fields in a filter.

Request:

https://www.devtodev.com/api/v1/labels/get

POST

{
	"user_token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
	"app_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
	"filters": {
		"id": {
			"in": [100500, 100501]
		},
		"category": {
			"in": ["category name", "category name 2"]
		},
		"start_date": {
			"gte": 1478625206
		},
		"end_date": {
			"lte": 1478625206
		}
	}
}

Response:

{
	"status_code": 200,
	"data": {
		"status": "complete",
		"labels": [{
			"id": 100500,
			"name": "label name",
			"description": "short label description",
			"category": "category name",
			"start_date": 1478625206,
			"end_date": 1478625206
		}]
	}
}

List of comparison operators that can be applied in a filter

The filter can be described with an object, where the following comparison operators can be the properties:

API operator	Math operator	Description
gt	>	Greater than
lt	<	Less than
eq	=	Equal
gte	>=	Greater than or equal
lte	<=	Less than or equal
neq	!=	Not equal
eq		In the list
neq		Not in the list

The empty object describes the filter that selects all the events in which the parameter value is not null or empty string.

Adding labels

In case the specified category doesn't exist, it will be created. If string values of fields exceed the maximum, they will be cut off.

If you need to specify an event without time length, start_date must be equal to end_date or end_date must not be specified.

Request:

https://www.devtodev.com/api/v1/labels/add

POST

{
	"user_token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
	"app_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
	"labels": [{
		"name": "label name",
		"description": "short label description",
		"category": "category name",
		"start_date": 1478625206,
		"end_date": 1478625206
	}]
}

Response:

{
	"status_code": 201,
	"data": {
		"status": "created",
		"labels": [{
			"id": 100500,
			"name": "label name",
			"description": "short label description",
			"category": "category name",
			"start_date": 1478625206,
			"end_date": 1478625206
		}]
	}
}

Editing labels

To edit a label you need to specify its identifier (id). All the specified fields for the label will be replaced. In case the specified category doesn't exist, it will be created.

If it is necessary to change the dates of an event, you must specify start_date. It is impossible to specify end_date without specifying start_date. If the label is used in relation to a continuous event (start_data and end_date are different timestamps), but in an edited version only the start_date is received, the label becomes a point that characterizes an instant event.

Request:

https://www.devtodev.com/api/v1/labels/edit

POST

{
	"user_token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
	"app_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
	"id": 100500,
	"name": "label name",
	"description": "short label description",
	"category": "category name",
	"start_date": 1478625206,
	"end_date": 1478625206
}

Response:

{
	"status_code": 200,
	"data": {
		"status": "complete",
		"labels": [{
			"id": 100500,
			"name": "label name",
			"description": "short label description",
			"category": "category name",
			"start_date": 1478625206,
			"end_date": 1478625206
		}]
	}
}

Deleting labels

The request is used to delete one or several labels. To delete a label its identifier is required. The request without specified identifiers is not valid.

Request:

https://www.devtodev.com/api/v1/labels/delete

POST

{
	"user_token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
	"app_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
	"ids": [100500, 100501]
}

Response:

{
	"status_code": 200,
	"data": {
		"status": "deleted",
		"labels": [{
			"id": 100500,
			"name": "label name",
			"description": "short label description",
			"category": "category name",
			"start_date": 1478625206,
			"end_date": 1478625206
		}]
	}
}

Error handling

In case there is an error in a request, the response is made in the following format:

{
	"status_code": 500,
	"errors": [{
		"code": 3,
		"msg": "Malformed json"
	}]
}

where

• status_code (number) - the general status of an error

• errors (array) - an array of error descriptions

• code (number) - the exact code of an error from the table of errors

• msg (string) - a brief description of an error

The list of possible errors is given in a table.

List of possible errors

Status code	Code	Value of "msg" field	Error description
500	1	Unknown Error	Unknown error. In case it repeats, please contact technical support.
400	2	Request body is empty	Request body is empty. There is no POST data in the request.
400	3	Malformed json	There is an error of JSON format in the request body. Fix the error of format.
400	4	Field not found: %field_name%	The required field is not specified in the request. Please add it to the request.
400	5	Field %field_name% has type %received_type% but %expected_type% expected	The type of data doesn't match the expected type. Follow the recommendation and change the data type to the expected one. It is possible to use the following types of data: boolean, integer, float, number (integer+float), string.
400	6	Invalid app id %app id value%	The requested app is not found. The app is unknown. The error can appear in case the specified app identifier is wrong or when the app has been removed.
401	11	Authorization error. Wrong user token %user_token value%	Authorization error. The specified User API token is wrong. Check the value of the specified key.
401	12	Authorization error. User_token is not set.	Authorization error. User API token is not specified in the request parameters. It is necessary to specify User API token ("user_token" field) in every request.
403	13	Access denied. You have no access to the app %app id value%	Access error. The owner specified in the User API token request has no access rights to the app specified in the same request.
403	15	Access denied. You have no access to API.	Access error. You have no access to devtodev API. The error can appear when User API token owner's access rights to the service API are changed as a result of the change of the user's role or the change of the price plan.
403	23	Access denied. You have no access to Labels API.	Access error. The error can appear in case the User API token owner has no access to the Labels API service due to the limitations of the user's role or limitations of the price plan of the space.
400	28	Unexpected value for field %field%. Received value: %value%. Expected values: %values%.	Unexpected value for the field. Follow the recommendations and correct the request.
400	29	Unexpected field %field%	The request contains the field that is not specified in the documentation. The field must be excluded from the request.
400	30	Invalid value for field %field%. Received value: %value%. Expected: %description%	Invalid value has been attributed to the field. Follow the recommendations and correct the request.
404	34	No results matched the request	The requested data is missing.
429	35	Quota exceeded. %% new labels per day per application quota has been exceeded.	The daily limit is exceeded. Tomorrow you will be able to add labels to the app again.
400	37	New labels array should not contain more than %% elements.	The array of labels contains more than 30 elements. Reduce the number of labels created in one request.
429	36	Quota exceeded. %% new labels per day per user quota has been exceeded.	The daily limit is exceeded. You will be able to add a new set of labels tomorrow.
400	38	Labels feature is not available for cross-platform projects	The labels feature is not available for cross-platform projects. Labels can be applied only to ordinary apps or branch-apps of cross-platform projects.

Limitations

Limitations on the lenght of values

Name	Field	Limitation
Label name	name	not more than 10 symbols
Short description of a label	description	not more than 512 symbols
Category name	category	not more than 30 symbols

Limitations on the number of actions

• Not more than 30 labels in one request on labels creation

• Not more than 500 labels to be created in a calendar day for User API token

• Not more than 200 labels to be created in a calendar day for an app