Subscribing using product identifiers
Retrieve components, that are linked to a particular product, use Get Product Components endpoint.
Example in python:
import requests
http = requests.Session
http.headers['x-api-key'] = marketplace_api_key
def get_components(marketplace_env: str, product_id: str) -> list[str]:
response = http.get(f"")
return response.json['components']
component_names = [
*get_components(marketplace_domain_name, product_id_of_connector),
*get_components(marketplace_domain_name, product_id_of_persistence),
]
http.post(
"",
json={
"domain_name": subscriber_domain_name,
"api_key": subscriber_api_key,
"component_names": component_names,
},
)
You can read more about linking a component to a product here
Subscription status
Status changes when subscription-specific operations occur. For example, if the Component to which you're subscribed gets an update, or you create a subscription.
The following is an ordered flow for the subscription status changes.
Observe delivery status
One way of observing deliveries' statuses in your environment is using Listen to Deliveries API.
However, if you don't need to monitor deliveries continuously – you can tell Marketplace to notify you once the component you initiated a direct subscription to has or hasn't been successfully delivered. The notification is emitted via the “webhook” with a structure of its payload described below.
Delivery statuses of dependencies are included only if there were failed deliveries
Events are sent in payloads of a “HTTP requests” using POST method.
{
"$schema": "",
"additionalProperties": true,
"type": "object",
"description": "Schema for the payload event emitted to callback.",
"properties": {
"transaction_id": {
"type": "string",
"description": "Transaction identifier. Unique per delivery."
},
"truncated": {
"type": "boolean",
"description": "Event can be truncated if many direct subscriptions were initiated."
},
"domain_name": {
"type": "string",
"description": "Subscription receiver domain name."
},
"components": {
"type": "array",
"description": "List of components subscription was initiated for.",
"items": {
"type": "object",
"properties": {
"component_name": {
"type": "string",
"description": "Component name delivery initiated for."
},
"last_deployment_id": {
"type": "string",
"description": "Latest available deployment ID used in delivery. Can be null."
},
"delivery_status": {
"type": "string",
"enum": [
"FAILED",
"SUCCEEDED"
],
"description": "The status of the delivery."
},
"component_publication_id": {
"type": "string",
"description": "The bundle ID of a component used in the delivery process. Can be null."
},
"status_updated_date": {
"type": "string",
"description": "Last time the status was updated."
}
}
}
},
"failed_dependencies": {
"type": "array",
"description": "List of components subscription was initiated for.",
"items": {
"type": "object",
"properties": {
"component_name": {
"type": "string",
"description": "Component name delivery initiated for."
},
"last_deployment_id": {
"type": "string",
"description": "Latest available deployment ID used in delivery. Can be null."
},
"delivery_status": {
"type": "string",
"enum": [
"FAILED",
"SUCCEEDED"
],
"description": "The status of the delivery."
},
"component_publication_id": {
"type": "string",
"description": "The bundle ID of a component used in the delivery process. Can be null."
},
"status_updated_date": {
"type": "string",
"description": "Last time the status was updated."
}
}
}
}
}
}
Troubleshooting
Events are dispatched once the delivery process completes,
which includes the successful or failed deployment of all components
and their respective dependencies.
An event is deemed as successfully delivered when its recipient acknowledges
with an HTTP status code that falls within the range of successful responses.
If an event isn't successfully delivered,
the Marketplace will make six additional attempts to resend the event,
with each attempt following an exponential back off strategy.
To confirm the propagation of the webhook,
you can utilize Retrieve Transaction Collections with the transaction ID,
which is returned during the creation of the subscription.
Collection data example:
{
"delivery": {
"components": [
{
"status_updated_date": "2023-05-05T12:28:38.547030+00:00",
"component_name": "Marketplace",
"delivery_status": "SUCCEEDED",
"component_publication_id": "01H01965DB8QGSD9EZWF1VS7BC"
},
{
"status_updated_date": "2023-05-05T12:28:38.547030+00:00",
"component_name": "marketplace-ontology",
"delivery_status": "SUCCEEDED",
"component_publication_id": "01G02003BD8GQSD9ZEFF1BEVND"
}
],
"domain_name": "tea.staircaseapi.com",
"failed_dependencies": [],
"truncated": false
},
"partner_response": {
"request_response_elapsed_time": 0.38052,
"response_status_code": 200,
"response_text": "{\"message\": \"event_received\"}",
"http_connection_established": true
}
}
Collection is not yet valid for the Lexicon version 3.
Deprecation notice
Marketplace will stop accepting products and data fields starting from December 2022.
In order to subscribe to components, please use component_names field instead.
Example:
import requests
requests.patch(
"",
json={
"domain_name": subscriber_domain_name,
"api_key": subscriber_api_key,
"component_names": [
"Connector",
"Deploy",
"Health",
],
},
)
Open endpoint
This endpoint is open. Endpoint is open, when you can omit request authorization via x-api-key header.
Subscriber validation
Marketplace will validate domain_name to api_key attachment to verify the claim of the environment ownership.
Depending on the ownership validation results, Marketplace can either abort or the request or carry on with the subscription changes.
