App Offerings API

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.

Filtering

Filtering is available for the following fields:

id source sourceID reference name created_at updated_at disabled

Sorting

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

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

id sourceID name, 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
card_description
Optional string (max 255) — Short description of the app offering to be shown on the card in the App store.
configuration_uri_template
Optional string (max 255) — The URI where the app can be configured. The placeholder {account} can be used to include the customer account id in the URI.
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.
compliance_attachments
Writeonly attachments The attachments used in the Compliance field.
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.
description_attachments
Writeonly attachments The attachments used in the Description field.
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.
features_attachments
Writeonly attachments The attachments used in the Features field.
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 string (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.
requires_enabled_oauth_person
Optional boolean, default: false — This app requires an enabled OAuth person, which makes it @mentionable and visible like a real person..
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.