Skip to main content

Ordering V2 Migration

The Hub Ordering API is now on version 2. V1 will be available for two weeks until November 11th. Data from V1 orders will be migrated to V2 on October 27th with the cutover and then again on November 12th. This document explains the changes.

Key Points​

  • Order API version 2 is primarily back-end improvements to the systems that handle orders and deliveries.
  • For users, there are no changes to the API requests.
  • Orders and Monitors created in V1 will be automatically migrated to V2.
  • The only user-facing changes relate to the "Download" delivery method:
    • The download link no longer uses a pre-signed URL.
    • Requests for the download URL now require Hub authentication, using either an OAuth bearer token or API key.
    • The download link in the order success notification email is no longer a clickable link.

Ordering V2 API changes​

Ordering V2 consists almost entirely of improvements to the back-end infrastructure that handles orders and deliveries. Out of an abundance of caution, the new infrastructure has been isolated to a new API version. Since monitors can place orders, auto-ordering monitors will also use the new ordering system.

URL structures will remain the same. The only change between URLs will be the v1 and v2 paths.

API requests and response schemas are unchanged. The paths will accept the same parameters and payloads and return similar responses.

The only change required to send V2 requests is to change the path name to use the v2 path.

Data Migration​

Order data will be migrated from V1 to V2, meaning you will see existing V1 order data in V2.

Data migration #1: The morning of October 27th, prior to the V2 release Data migration #2: The morning of Nov 12th, the day after the final migration day, to move any orders placed in V1 during the migration period.

Between these two data migrations, you can expect the following: • If you place orders on V1, you will need to make any GET order details requests to the V1 endpoint. For V2 orders, you will get status from the V2 endpoint. • Orders placed to the V1 endpoint during the migration period will not be viewable in the Hub UI until after the final data migration.

Download delivery changes​

The V1 Ordering API returned a pre-signed URL for the output file. To improve security, the download URL no longer includes pre-signed credentials. Requests for the file now require Hub authentication added to the request. This can be either an OAuth bearer token or an API key. See the authentication section.

Email notifications​

Notification emails from Ordering API V1 used an html anchor <a> to make the file path a clickable download. Because V2 links now require authentication be added to request, this means that if a web browser tries to download the file it will fail with a 403 error.

V2 emails will still wrap the file location in a <a> tag but there is no longer an href attribute. If you are parsing the email, Use the anchor text instead.

Order Details and Events responses​

The object representing the download delivery in the Order Details response, and the serialized JSON representation in the Order Events are unchanged in schema. Only their values will change to reflect the new download links.

V1 delivery object:

{
      "type": "download",
      "links": [
          "<DOWNLOAD LINK WITH PRESIGNED URL>"
      ],
      "instructions": "Please click the included links to download your ordered products.",
      "archive_format": "zip"
    }
}

V2:

{
    "type": "download",
    "links": [
        "https://api.maxar.com/ordering/v2/orders/<ORDER ID>/download"
    ],
    "instructions": "Download your order using the provided link.",
    "archive_format": "zip"
}

Download API endpoint​

An order's download can be retrieved from:

GET https://api.maxar.com/ordering/v2/orders/<ORDER ID>/download

The request requires some form of Hub authentication.

The files are stored for two weeks. If you try to download a file after it has been cleaned up, you will receive an error message stating clearly that the file is no longer available.

Similarly, if you try to download a file before it has been delivered, the error message will state the order has not finished yet.

Because the download link includes the order ID, it now possible to poll the API to see if the download is ready. This may simplify some workflows.

Last updated on