App Actions

App Action is an entity that allows communication between apps. An app can expose actions that the other apps can call to trigger specific behaviors.

Actions are asynchronous and don’t return a payload directly to the caller. The execution outcome (status, structured result, or error) is persisted on an App Action Call and can be retrieved via the App Action Call endpoints. One can think about an AppAction as an asynchronous function whose result is recorded and can later be retrieved.

Notes

ActionConsumer is a user or an app that triggers behaviours in other apps.
ActionProvider is an app that exposes actions that other users or apps can trigger.

The diagram below displays an interaction between ActionProvider, ActionConsumer and CMA when an App Action is called.

app action flow

In order to trigger an action on your app, a ActionConsumer needs to make a call to the CMA: Contentful will then send a signed request to your application. This comes with the following out-of-the-box features:

Apps exposing actions are secured by request verification.
Action parameters are pre-validated (with a provided schema) by Contentful.
Actions can be triggered if and only if both ActionConsumer and ActionProvider have access to the same space-environment.

See an example implementation of an App Action in the code example below:

import createApp from 'imaginary-http-framework';
import { verifyRequest } from "@contentful/node-apps-toolkit";
import { sendNotification } from './service/imaginary';
import { signingSecret } from './secure-storage';
const app = createApp();
app.post('/send_notification', async (req, res, next) => {
    const canonicalRequest = {
        method: req.method,
        path. req.url,
        headers: req.headers,
        body: req.body,
    }
    if (!verifyRequest(signingSecret, canonicalRequest)) {
        next(new Error('409 - Conflict, signature does not match'));
        return;
    }
    const response = await sendNotification(req.body);
    res.send(200)
})
app.listen(3000)

Notes

When working with App Actions, consider the following:

Actions can only be triggered by apps with app identities.
Actions are asynchronous and don’t yield a response.
Only apps with signing secret can expose actions.

Errors

409 - Forbidden - This error is returned if signing secret is invalid or missing.

App Actions collection

These endpoints are meant to be used to manage actions to be consumed by other apps. The endpoints to trigger actions are documented in the next section.

Action consumers rely heavily on the schemas exposed by your app. Introduce changes to the schema with care, or consider creating different actions for versioning.

Get all actions of an app

Create an action

App Actions of Environment

Get all actions of an environment

App Action

These endpoints are meant to be used to manage actions to be consumed by other apps. The endpoints to trigger actions are documented in App Actions calls.

Update an action

Read an action

Delete an action