Set Key-Value¶

Description¶

This operation modifies a value associated with the specified key. In case the specified key does not exists, a new key-value pair is created.

Method¶

PUT

Endpoint URL¶

Important

Make sure to replace xxxx in the domain name in the request specification below to the one assigned to your application.

https://xxxx.backendless.app/api/hive/[hive-name]/key-value/[key]

where:

Argument	Description
`[hive-name]`	Name of a hive where the operation is performed.
`[key]`	Key name identifying a key-value pair.

Request Headers¶

Content-Type:application/json

where:

Argument	Description
`Content-Type`	Must be set to `application/json`. This header is mandatory.

Request Body¶

The request body must be a JSON object with the structure shown below:

{  
    "value": <string>,  
    "ttl": <integer>,      // optional (in seconds)  
    "expireAt": <integer>, // optional (in seconds)  
    "condition": "IfExists" | "IfNotExists" | "Always" // optional, if not provided, defaults to "Always"  
}

where:

Argument	Description
`"value"`	A value to assign to the key.
`"expireAt"`	Optional parameter. A Unix timestamp identifying a moment in time when the key-value pair must expire and be subsequently removed from the store. The Unix time is the number of seconds elapsed since `1970-01-01 00:00:00 UTC`.
`"ttl"`	Optional parameter. This parameter is interpreted as a number of seconds after the value is created or updated when the key-value pair expires and is subsequently removed from the store. If the request body contains values for both `"ttl"` and `"expireAt"` , the `"ttl"` parameter is ignored.
`"condition"`	Optional parameter. This parameter sets a condition for when the key-value is created or modified. Supported values are: `"IfNotExists"` - a new key-value pair is created only if the specified key does not exist. If the key exists, the value is not updated. `"IfExists"` - the value is updated only if the specified the key exists. If the key does not exist, a new key-value pair is not created. `"Always"` - works both ways and creates a new value if it does not exist or modifies an existing value if the key exists.

Response Body¶

The operation returns true when:

The "condition" parameter is set to "Always" or;
The condition is met for the "IfExists" or the "IfNotExists" options

In all other cases, the return value is false.

Example¶

The example below modifies the value associated with the key Japan to "The land of the rising sun". The "condition" parameter is set to "Always", as a result, if the specified key does not exist, a new key-value pair is created.

The "ttl" parameter is set to 100 seconds, as a result, the newly created/modified key is deleted by the system 100 seconds after the call.

curl --location --request PUT "https://xxxx.backendless.app/api/hive/countries/key-value/Japan" \--header 'Content-Type: application/json' \--data-raw '{"value": "The land of the rising sun", "ttl": 100, "condition": "Always"}'

where:

Argument	Description
`countries`	Name of a hive where the operation is performed.
`Japan`	A key to modify the value for.
`"The land of the rising sun"`	The new value to assign to the key.

Codeless Reference¶

keyvalue_api_set_key_value

where:

Argument	Description
`hive name`	Name of a hive where the operation is performed.
`key name`	Key name identifying a key-value pair.
`value`	A new value for a key.
`expire`	Expiration timeout type. Can be set to `seconds after` or `on timestamp/date`. The `seconds after` identifies the number of seconds until the key expires. The `on timestamp/date` identifies a Unix timestamp/date when the key must expire. This option expects the number of seconds in the Unix format.
`expire condition`	Sets a condition for when the key-value is created or modified. There are three supported conditions: `If Exists` - a new key-value pair is created only if the specified key does not exist. If the key exists, the value is not updated. `If Doesn't Exist` - the value is updated only if the specified the key exists. If the key does not exist, a new key-value pair is not created. `Always` - works both ways and creates a new value if it does not exist or modifies an existing value if the key exists.

Returns a boolean value depending on the selected parameters.

Consider the following Key Value storage:

sample-key-value

The example below a value for the "Japan" key:

keyvalue_api_example_set_key_value

The key-value storage will look as shown below after the Codeless logic runs:
keyvalue_api_example_set_key_value_2