App Offerings API

App Offerings are a new feature currently in beta-test: this API is subject to change without notice. Visit App Builder NodeJS for more information on apps in 4me.

List app offerings

List all app offerings for an account:

GET /app_offerings

Response

Status: 200 OK
[
  {
    "id": 1,
    "sourceID": null,
    "reference": "note-dispatcher",
    "name": "Log Note Dispatcher Integration",
    "created_at": "2021-04-13T04:19:49-05:00",
    "updated_at": "2021-04-13T04:19:51-05:00",
    "service_instance": {
      "id": 83,
      "name": "Our Integration"
    },
    "policy_jwt_alg": "rs512",
    "webhook_uri_template": "https://jfgd645.execute-api.eu-west-1.amazonaws.com/Prod/integration/?account={account}",
    "...": "..."
  },
  "..."
]

The response contains these fields by default. Filtering and pagination are available to reduce/limit the collection of app offerings.

Predefined Filters

The following predefined filters are available:

Collection Fields

By default the following fields will appear in collections of app offerings:

created_at id name nodeID policy_jwt_alg policy_jwt_audience policy_jwt_claim_expires_in reference service_instance sourceID updated_at webhook_uri_template

Obtain a different set of fields using the ?fields= parameter.

Sorting

By default a collection of app offerings is sorted ascending by reference.

The following fields are accepted by the ?sort= parameter:

id sourceID reference created_at updated_at

Get a single app offering

GET /app_offerings/:id

Response

Status: 200 OK
{
  "id": 1,
  "sourceID": null,
  "reference": "note-dispatcher",
  "name": "Log Note Dispatcher Integration",
  "created_at": "2021-04-13T04:19:49-05:00",
  "updated_at": "2021-04-13T04:19:51-05:00",
  "service_instance": {
    "id": 83,
    "name": "Our Integration"
  },
  "policy_jwt_alg": "rs512",
  "webhook_uri_template": "https://jfgd645.execute-api.eu-west-1.amazonaws.com/Prod/integration/?account={account}",
  "...": "..."
}

The response contains these fields.

Create an app offering

POST /app_offerings

When creating a new app offering these fields are available.

Response

Status: 201 Created
{
  "name": "...",
  "...": "..."
}

The response contains all fields of the created app offering and is similar to the response in Get a single app offering.

Update an app offering

PATCH /app_offerings/:id

When updating an app offering these fields are available.

Response

Status: 200 OK
{
  "name": "...",
  "...": "..."
}

The response contains all fields of the updated integration and is similar to the response in Get a single app offering.

Fields

attachments
Readonly aggregated Attachments
compliance
Optional text (max 64KB) — The Compliance field is used to enter the compliance statement for the app offering. This is shown to customers on the ‘Security & Compliance’ tab in the Apps section for this app.
created_at
Readonly datetime — The date and time at which the app offering was created.
description
Optional text (max 64KB) — The Description field is used to enter a description of the app offering. This is shown to customers on its own tab in the Apps section for this app.
disabled
Optional boolean, default: false — The Disabled box is checked when the app may no longer be installed by new customers. Customers that have an older version installed can still update when the app offering is disabled.
features
Optional text (max 64KB) — The Feature field is used to elaborate on the features of the app offering. This is shown to customers on its own tab in the Apps section for this app.
id
Readonly integer — The unique ID of the app offering.
name
Required string (max 128) — The Name field is used to enter the name of the app offering.
picture_uri
Optional string — The hyperlink to the image file for the app offering.
policy_jwt_alg
Required enum — The algorithm used for generating the policy for the app’s webhook. Valid values are:
  • rs256: RSA using SHA-256
  • rs384: RSA using SHA-384
  • rs512: RSA using SHA-512
  • es256: ECDSA using P-256 and SHA-256
  • es384: ECDSA using P-384 and SHA-384
  • es512: ECDSA using P-521 and SHA-512
policy_jwt_audience
Optional text (max 2KB) — The audience for the policy for the app’s webhook.
policy_jwt_claim_expires_in
Optional duration — The claim expiry time for the policy for the app’s webhook.
reference
Required string (max 161) — The Reference field can be used to identify the app offering via the APIs, it is the only identifier that will remain stable across version updates. It may only be changed until the app offering is published for the first time. The Reference field defaults to the Name field value, written in lower case characters and with all spaces replaced by the underscore character, prefixed with the account name followed with an underscore (e.g. wdc_). It must be unique across all accounts.
service_instance
Required reference to Service Instance — The Service instance field is used to select the Service Instance that should be used when creating Requests regarding this app offering.
source
Optional string (max 30) - See source
sourceID
Optional string (max 128) - See source
ui_extension_version
Optional reference to UI Extension Version — The UI extension version field is used to select the (version of the) UI extension for this app offering’s instances. The UI extension is shown on the ‘Configuration’ tab in the Apps section for customers that install this app offering.
updated_at
Readonly datetime — The date and time of the last update of the integration. If the app offering has no updates it contains the created_at value.
webhook_uri_template
Required string (max 255) — The URI for the app’s webhook. The placeholder {account} can be used to include the customer account id in the URI.