API changelog
This changelog lists all of the user-facing changes to API Platform in version 2.
Breaking changes
-
POST /tasking/v2/tasks
endpoint — the type of theimagingMode
parameter in the API specification of thecreateTask
operation has changed fromenum
tostring
.Instead of enumerating the list of available imaging modes in the API specification, the available imaging modes are now taken from your contract. This change should not immediately impact an existing client runtime, because the format of a
createTask
request is unchanged. But if your client implementation relies on generating code from the API specification, this could have an impact on your client codebase.
Non-breaking changes
-
POST /notifications/v1/webhooks
endpoint — theregisterWebhook
operation can now be configured to send OAuth2 client credentials in notification callbacks, in order to support the OAuth2 Client Credentials authentication flow on a callback HTTPS server.
Breaking changes
-
GET /catalog/v2/items
andPOST /catalog/v2/search
endpoint — response messages from thelistCatalogItems
operation and thesearchCatalogItems
operation now usestart_datetime
andend_datetime
properties, instead ofstart_time
andend_time
.
Non-breaking changes
-
GET /delivery/v1/deliveries
endpoint — new listDeliveries operation enables you to get a list of all delivery objects associated with your account. -
GET /company/v1/contracts/{contractID}
andGET /company/v1/contracts
endpoints — now returncatalog_collections.allowed
andcatalog_collections.default
values in each catalog resource, enabling you to discover the catalog collections associated with your contract. -
GET /catalog/v2/items
andPOST /catalog/v2/search
endpoints — the searchCatalogItems and listCatalogItems operations now support filtering by catalog collection.
-
POST /delivery/v1/deliveries
andGET /delivery/v1/deliveries/{id}
endpoints — if delivery notification was enabled, thecreateDelivery
andgetDelivery
operations now include a copy of the notification resource in the body of their responses. -
GET /tasking/v2/tasks
endpoint — thelistTasks
operation response has been simplified such that it no longer includes the array of delivery locations associated with each task.
-
POST /delivery/v1/deliveries
endpoint — the newcreateDelivery
operation can be used to request delivery of multiple imaging products as separate files. You can request delivery of any STAC items that you own (including images you have previously tasked with PRIVATE exclusivity) using this operation. -
POST /catalog/v2/search
endpoint — thesearchCatalogItems
endpoint now supports filtering results by intersection with a GeoJSON polygon object, using theintersects
request parameter.
New APIs
The following APIs are new in API Platform 2.0:
-
Delivery API — a new API that enables you to request delivery of your tasked products or any products you purchased from the public catalog. See Delivery.
-
Notifications API — a new API for handling asynchronous interactions. The Notifications API enables you to use webhooks to learn when resources are updated in the ICEYE system. See Notifications.
Updated APIs
Tasking API
The following operations have changed in v2:
-
POST /tasking/v2/tasks
endpoint — the Create task operation has changed as follows:-
A new
notifications
parameter is provided, which you can configure to receive callbacks from the notification service whenever the task status changes. -
The
deliveryLocations
parameter has been replaced by thedeliveries
parameter, which enables you to configure delivery locations in a manner that is consistent with the new Delivery API. -
The
additionalProductTypes
parameter has been removed. The SLA products delivered for a tasking request are now managed by your company’s contract and changes to the SLA products can be requested by contacting the COSP team.
-
-
GET /tasking/v2/tasks/:taskID
endpoint — in the Get task operation, the response now includes fields fordeliveries
andnotifications
. -
GET /tasking/v2/tasks/:taskID/products
andGET tasking/v2/tasks/:taskID/products/:productType
endpoints — in the Get products and Get products by type operations, the response is similar to the Catalog API and includes many additional properties in the product description.
Catalog API
The Catalog API now provides access not just to the public catalog, but also to the private images you have previously tasked (associated with the company of the currently authenticated user).
The following operations are new in v2:
-
GET /catalog/v2/price
endpoint — using the Get frame price operation, you can check the price of a frame before purchasing (for contracts that have an associated pricing model).
The following operations have changed in v2:
-
GET /catalog/v2/items
endpoint — in the List catalog items operation, the variety of properties that can be provided to thesortby
query parameter has been extended and existing property names have been modified to conform to the STAC standard.STAC items returned from this operation now include additional properties.
-
POST /catalog/v2/search
endpoint — in the Search catalog items operation, the number of different properties you can provide in a STAC metadata query has been extended. See Filtering by STAC metadata query.STAC items returned from this operation now include additional properties.
-
POST /catalog/v2/purchases
endpoint — in the Purchase frame operation, an image is purchased by frame, not by STAC item. The following changes were made to this endpoint:-
To purchase a frame, specify the
frameID
(instead of a list of item IDs). -
Instead of specifying the
companyName
andcontactPerson
parameters, set the optionaleula
parameter. -
The response message has a new format, which includes the purchase ID, frame ID, and status.
-
-
GET /catalog/v2/purchases/:PURCHASE_ID
endpoint — in the Get purchase operation, the response message has a new format, which includes the purchase ID and frame ID. -
GET /catalog/v2/purchases
endpoint — in the List purchases operation, the purchase records returned in the response have a new format. -
GET /catalog/v2/purchases/:PURCHASE_ID/products
endpoint — in the List purchase products operation, the format of the STAC items returned from this operation has been modified and extended to include many more properties.
Searchable properties
API Platform 2.0 adds new searchable STAC item properties and updates existing property names to conform to the STAC standards.
The following properties were removed:
-
image_mode
— was removed in 2.0. Usesar:instrument_mode
instead. -
incidence_angle
— was removed in 2.0. Useiceye:incidence_center
instead.
The following properties were renamed to conform to the STAC item specification (using prefixes):
API Platform 1.0 property name | API Platform 2.0 property name |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
The following STAC item properties were added:
New API Platform 2.0 property |
---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Documentation website
The API Platform documentation has been migrated to a new website, with the following changes:
-
A search box is provided (top right) for User Guide content.
-
An Atom/RSS feed is provided for changelog updates: https://docs.iceye.com/constellation/api/blogs/atom