If you’re a user of the Akoya Apps Management API, we’re pleased to announce exciting changes to the Akoya network that will make app subscriptions even easier. To support these enhancements, we’ll be releasing v2 of the Akoya Apps Management API. V2 will have changes that will impact the behavior of v1. Why are we making these changes? Many customers have asked for a simplification of our subscription process. To do this, and improve your experience, we will make the updates described below.
Note: If you don’t plan to use the Apps Management API in the future, this version update will not impact you. If you’re new to Apps Management API, please only use version 2 as version 1 will be deprecated.
When will this happen?
Version 2 of the Apps Management API will launch in July. At that time, the automated subscriptions enhancement will mean that v1 will be automatically deprecated. Until the sunset date (six months after the v2 launch), v1 will continue to work with the following changes in behavior:
- When new providers are added to the network, all apps, including those created with v1, will be automatically subscribed to those new providers.
- When v1 is sunset, your apps will be automatically subscribed to providers that support the app’s requested products.
If you currently use v1 and plan on using the Management API in the future, you should plan migration to v2.
When you're ready to migrate to Apps Management v2, please inform your Customer Success Manager so we can authorize you for v2.
What’s changing?
We’re simplifying the data provider subscription process with automation. This means that when you create an app, we will determine which data providers support your requested products and automatically subscribe your app(s) to those providers. You’ll no longer need to request a subscription to a provider after app creation. Due to this, the Subscription endpoint is no longer necessary and will not be supported in v2.
All providers that support a new product will receive a connection request. Turnaround time for requests will stay the same (up to two weeks, depending on provider).
We’re also updating our app creation endpoint to meet the register DCR (Dynamic Client Registration) and FDX endpoint specifications. This will allow easier integration for recipients who already leverage the DCR or FDX specifications.
V2 overview and documentation
This migration guide covers the following changes at a high level. For more detailed documentation, please refer to the API documentation for Apps Management API v2.
- The app creation endpoint will be changed to meet DCR and FDX specifications
- Several endpoints will be updated so that values expected in DCR app creation are consistently used across all Management API endpoints.
- Pagination will be updated to be consistent with our data APIs.
- The PATCH endpoint will be updated to use JSON PATCH, specified in IETF’s RFC 6902.
Endpoints that will change
| Endpoint | Details |
|---|---|
| Get providers by Akoya product | Request * Query params: * register- no longer supported * products- assumes account_info, not required Response * The following JSON keys have changed: * provider_id[string]* display_name[string] * Includes more data for each provider: * provider_url[string] |
| Create your app(s) | Request * Body * The following JSON keys have changed and updated to DCR specification: * client_name* client_uri* logo_uri* icon_url* redirect_uris* scope(Akoya products)* subscriptions- no longer necessary and is not returned Response * The following JSON keys have changed and updated to DCR specification: * client_id* client_secret |
| Update your app details | Request (see details below) * Now follows JSON PATCH specification (RFC 6902) with support for: * add (arrays and struct fields) * remove (arrays only) * replace (all struct fields) * Body * The following JSON keys have changed and updated to DCR specification: * client_name* client_uri* logo_uri* icon_url* redirect_urisResponse * The following JSON keys have changed and updated to DCR specification: * client_id* owneris no longer in the response |
| Get list of your apps | Response * Body * The following JSON keys have changed and updated to DCR specification: * client_name * client_uri * logo_uri * icon_url * redirect_uris * now includes scope for Akoya productsResponse * The following JSON keys have changed: * client_id* provider_id* owneris no longer in the response |
| Get app subscription details | Response * The following JSON keys have changed: * provider_id[string]* display_name[string]* account_categoriesarray [string]* modification_request[object] * Includes more data for each provider: * logo[object]* icon[object] |
| Create or add subscriptions | REMOVED This endpoint will no longer be supported. |
| Get Subscription status by app | * The following JSON keys have changed: * subscription_statusarray [object]* provider_id[string]* display_name[string] |
Endpoints that will not change
JSON PATCH
Note
client_nameand the Akoya products your app uses cannot be updated with this endpoint.
A JSON PATCH request updates only specified details for your app. The request is sent in the body of the request as a JSON document containing an array of objects. Each object represents an operation to be applied to your app’s details.
For each update, define the operation, the JSON pointer (which references the JSON key that will be updated), and the value.
Supported operations:
- add (arrays and struct fields)
- remove (arrays only)
- replace (all struct fields)
For instance, if you’d like to update your app’s description, you would use the “replace” operation, the JSON pointer “/description” and the new value, e.g. “Example new app description.”
[
{"op": "replace", "path": "/description", "value": "Example new app description"},
]
Another example request which includes a string value and an array value:
[
{"op": "replace", "path": "/client_name", "value": "app1"},
{"op": "replace", "path": "/contacts", "value": ["[email protected]", "[email protected]"]}
]
Resetting client_secret with PATCH
client_secret with PATCHTo reset an app’s client_secret, you should send an empty value for client_secret. The new secret will return in the response.
You cannot send your own value for the secret. If a value is sent for client_secret, it will be ignored and will not cause an error. You will receive a new secret in the response.
Pagination changes
Endpoints with pagination:
/recipients/:recipientId/apps/subscriptions/:appId/subscriptions/:appId/status/recipients/:recipientId/providers
Pagination will now be consistent with other Akoya endpoints and page with next and prev links.
The first page will have a next link if there is more than one page. As you page, the next and previous links will update. The follow example demonstrates the second page in the set with previous and next links.
"links": {
"next": {
"href": "/manage/v2/recipients/:recipientId/apps?offset=20&limit=10"
},
"prev": {
"href": "/manage/v2/recipients/:recipientId/apps?offset=0&limit=10"
}
}
Change log
| Date | Update |
|---|---|
| 2024-Oct-03 | Minor corrections |
| 2024-Aug-15 | Original |
Need help?
Check out our Developer Community, or visit the Support Center in the Data Recipient Hub.
Looking for provider nuance documentation?
All provider nuance documentation is available in the Data providers section in the Data Recipient Hub.
Still stuck?
For all production issues, submit a support ticket through the Data Recipient Hub. Our support team is standing by 24/7. Questions and non-production issues will be answered during business hours.