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:
/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-256rs384
: RSA using SHA-384rs512
: RSA using SHA-512es256
: ECDSA using P-256 and SHA-256es384
: ECDSA using P-384 and SHA-384es512
: 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.