App Offerings API

• List app offerings
• Get a single app offering
• Create an app offering
• Update an app offering
• Fields

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:

• /app_offerings/latest_internal : List all draft app offerings in the current account
• /app_offerings/latest_published : List the latest version of each app offering published by the current account
• /app_offerings/all_latest_published : List the latest version of each app offering published by the current account and its trusted accounts
• /app_offerings/consumed : List all app offerings installed in the current account

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.