Edit on GitHub

Key-value store

The Apps framework provides access to a simple key-value store for App-specific data. Keys are simple strings and values are any data that can be expressed in JSON.

There are three operations that can be performed against the key-value store:

Get the value of a key
Set the value of a key
Delete a key

The key-value store can be accessed in two ways:

Using HTTP REST endpoints
Using a driver

Access the key-value store with HTTP REST calls

Endpoint URL

The key-value store is accessed using a single HTTP REST endpoint:

<mattermost_site_url>/plugins/com.mattermost.apps/api/v1/kv/<my-key>

Replace <mattermost_site_url> with the base URL to the Mattermost server and <my-key> with the name of the key to add, modify, or delete. The <mattermost_site_url> value can be obtained from a call request context.

Authorization

An authorization token is required when invoking HTTP REST endpoints of the key-value store. The token must be set in the Authorization header as a bearer token. The acting user token can be obtained from a call request context where the acting_user_access_token expand field is set to all. The acting_user_access_token field of the call request context will contain the token.

Get a value with HTTP REST

Example HTTP request to get the value of key my-key:

GET /plugins/com.mattermost.apps/api/v1/kv/my-key HTTP/1.1
Authorization: Bearer xxxxxxxxxxxxxx

The HTTP response body will contain only the value of the requested key.

Set a value with HTTP REST

Example HTTP request to set the value of key my-key to a JSON object:

POST /plugins/com.mattermost.apps/api/v1/kv/my-key HTTP/1.1
Authorization: Bearer xxxxxxxxxxxxxx
Content-Type: application/json

{
    "object_with": "some_data"
}

Delete a value with HTTP REST

Example HTTP request to delete the key my-key:

DELETE /plugins/com.mattermost.apps/api/v1/kv/my-key HTTP/1.1
Authorization: Bearer xxxxxxxxxxxxxx

Access the key-value store with a driver

Get a value with a driver

Example Golang driver code to get the value of the key my-key:

// Create an instance of the REST API client, acting as a bot (vs. a user)
client := appclient.AsBot(callRequest.Context)
// Create an empty struct to hold the data
var myData string
// Retrieve the value of the key `my-key` into `myData`
err := client.KVGet("my-app", "my-key", &myData)
if err != nil {
    // handle the error
}

Set a value with a driver

Example Golang driver code to set the value of the key my-key:

// Create an instance of the REST API client, acting as a bot (vs. a user)
client := appclient.AsBot(callRequest.Context)
// Store the string `my-value` in the key `my-key`
// The `valueChanged` bool indicates if the value of the `my-key` key was changed
valueChanged, err := client.KVSet("my-app", "my-key", "my-value")
if err != nil {
    // handle the error
}

Store complex data

Example Golang driver code to store complex and nested data:

type TeamData struct {
    Name string `json:"name"`
    Id   string `json:"id"`
}
type NestedData struct {
    UserId     string   `json:"user_id"`
    IsEmployee bool     `json:"is_employee"`
    Team       TeamData `json:"team"`
}
// Construct the data to store
myData := NestedData{
    UserId: "7q7kaakokfdsdycy3pr9ctkc5r",
    IsEmployee: true,
    Team: TeamData{
        Name: "My Team",
        Id: "hoan6o9ws7rp5xj7wu9rmysrte",
    },
}
// Create an instance of the REST API client, acting as a bot (vs. a user)
client := appclient.AsBot(callRequest.Context)
// Store the `myData` struct in the key `my-key`
valueChanged, err := client.KVSet("my-app", "my-key", myData)
if err != nil {
    // handle the error
}

Retrieving nested data is the same as any other data:

// Create an empty struct to hold the data
myData := NestedData{
    Team: TeamData{},
}
// Create an instance of the REST API client, acting as a bot (vs. a user)
client := appclient.AsBot(callRequest.Context)
// Retrieve the value of the key `my-key` into `myData`
err := client.KVGet("my-app", "my-key", &myData)
if err != nil {
    // handle the error
}

Delete a key with a driver

Example Golang driver code to delete the key my-key:

// Create an instance of the REST API client, acting as a bot (vs. a user)
client := appclient.AsBot(callRequest.Context)
// Delete the key `my-key`
err := client.KVDelete("my-app", "my-key")
if err != nil {
    // handle the error
}