"createLabel"
Creates a new label
The "createLabel" action creates a new label with the required property "name" and optional properties "group", "sequence", "description", and "metadata". The server automatically generates an "id" value and uses it internally for referencing the label. If you use labels in your application, you should also use the "id" property to reference the label because it allows you to rename the label without breaking external references to it.
Request examples
Minimal
This example creates a label in the empty "group". It is best to create a label in a specific group.
{
"api": "admin",
"action": "createLabel",
"params": {
"name": "myLabelName"
},
"authToken": "replaceWithAuthTokenFromCreateSession"
}{
"api": "admin",
"action": "createLabel",
"params": {
"group": "myLabelGroupName",
"name": "myLabelName"
},
"authToken": "replaceWithAuthTokenFromCreateSession"
}
{
"api": "admin",
"action": "createLabel",
"params": {
"group": "myLabelGroupName",
"name": "mySecondLabelName",
"value": 99,
"enum": 0,
"sequence": 1.2,
"deprecated": false,
"description": "My label description.",
"metadata": { }
},
"authToken": "replaceWithAuthTokenFromCreateSession",
"apiVersion": "1.0",
"requestId": "3",
"debug": "max"
}{
"authToken": "authToken",
"result": {
"id": 1,
"group": "mylabelGroupName",
"name": "mylabelName",
"value": 99,
"enum": 0,
"sequence": 1.2,
"deprecated": false,
"description": "My label description.",
"metadata": {}
},
"errorCode": 0,
"errorMessage": "",
"debugInfo": {}
}
Create a new label using the "createLabel" action
"params" properties summaryProperty | Description | Default | Type | Limits (inclusive) | |||
|---|---|---|---|---|---|---|---|
(optional) specifies when a label is deprecated or not |
| Boolean |
| ||||
(optional) describes a label |
| string | 1 to 65,500 bytes | ||||
(optional) assigns an integer number to a label |
| smallint |
| ||||
(optional) assigns a group to a label to create named lookup lists and tag sets |
| string | 1 to 64 bytes | ||||
(optional) assigns metadata to a label |
| string | 0 to 65,500 bytes | ||||
names a label. The name must be unique in its group | Required - No default value | string | 1 to 64 bytes | ||||
(optional) specifies the numerical order of labels within a group |
| double | Any floating point or integer number | ||||
(optional) assigns a value to a label |
| string | 0 to 65,500 bytes |
The "deprecated" property optionally deprecates a label. Set it to true to deprecate a label and false when you do not. It defaults to false. Deprecating a label is similar to marking a label as deleted.
The "description" property optionally provides additional information about a label. You can use it as internal or external documentation about the meaning, purpose, and usage of a label.
Markdown is a good language for formatting description text. You must ensure the text is compatible with a JSON string. For example, you must escape a double quote character using the backslash character: \".
The "enum" property optionally assigns an integer from -32768 to 32767 to a label. You can use this property to assign an application's hardcoded enumerated value to a label.
The "group" property optionally groups labels into a lookup list or tag set. It is an optional namespace for a set of labels that identifies their purpose. You can use the "listLabelGroups" action to return the list groups. You can use the "listLabels" action to return labels in one or more groups.
The group name may contain up to 64 bytes of UTF-8 encoded characters.
If the "group" property is omitted when creating a label, the group defaults to the empty string, "", which is the catch-all group.
When you assign a group name to a label, the server automatically checks if the group name exists in the list of groups that the "listLabelGroups" action returns. If the group name does not exist, the server adds the group name to the list. When you rename a group assigned to a label, the server automatically adds a new group name to the list and removes the previous group name if no other label uses it.
Tip
If your application creates many groups, you can use a delimiter character, such as the forward slash / in your group names to create a group hierarchy. Include the delimiter after each part of the hierarchy and at the end of the group name. In the "listLabels" action, you can use the "partialGroupFilter" filter to return subsets of groups in the hierarchy. For example, you if have groups named "product/size/", "product/weight/", "product/ranking/", "person/gender/", and "person/ranking/", you can set the "partialGroupFilter" to "product/" to return the product groups.
The "metadata" field optionally allows a customer to add a JSON value to the label. It is typically a JSON object, but may be any JSON value. It defaults to null. Its purpose is to provide additional metadata about the label, such as translations in multiple languages, historical value changes, etc. The "alterLabel" action can only replace this value with a new JSON value.
The "name" property is the name of a label. It is a required UTF-8 string that is up to 64 bytes long.
The "group" and "name" properties combined uniquely identify each label. The "createLabel" and "alterLabel" actions return an error if the "group" and "name" properties do not create a unique label name.
The "id" property also uniquely identifies each label so you can rename a label's group and name without breaking "id" references to the label.
The "sequence" property optionally assigns an order to the labels in a group. You can use a floating point or integer number. You may embed the number in a JSON string. It defines the order of labels in a group. It is a floating point number to make it easy to change label order without renumbering all labels in a group. For example, to move a label in between two other labels, you can assign a fractional number to the label that is in between the sequence numbers of two other labels.
The "value" property associates a value with a label. It is an optional JSON value that is associated with a label. It can be any JSON value. It defaults to null.
When you use the "alterLabel" action to update the "value" property, it replaces "value" with an entirely new value. It cannot replace parts of the JSON value.