V3 Get Transaction endpoint change

We’re excited to announce an update to our API.

Release date: Feb 9th, 2021

Overview: Change of a property on the GET /v3/transactions/:id endpoint 

Purpose: In order to future proof an endpoint before anyone integrates to it we've added more functionality when retrieving a transaction.

This change comes with a helping of humility as we're doing something we said we wouldn't: making a breaking change to an API endpoint. After some future planning we've realized a recently released endpoint could be made more future-proof with a small modification. The only reason it's acceptable to make a breaking change is that our operational analytics indicate that no one has integrated to the endpoint yet. There are occasional test requests but no production loads relying on it.

The Change

If you recall the GET /v3/transactions/:id response payload you'll recall the message property currently looks like this:

"message": { 
    "content": {...}, 
    "validationStatus: "VALID", 
    "sizeInBytes": 3251, 
}

Here the content is a JSON object. While this covers today's use cases, we're currently designing out non-JSON payload support (e.g. XML, CSV, etc) – which obviously could not be returned as a JSON object. Also for future non-JSON payload you'll need to be able to access the original payload before conversion and the latest one after.

The path forward is to maintain our JSON-first API but separate the content out into its own endpoint which can support any content type. Now the message portion will be renamed to revisions and support both the transaction as posted and after processing. The property will now look like this:

"revisions": {
    "original": { 
        "content": "https://api.orderful.com/v3/transactions/123/content", 
        "validationStatus: "VALID", 
        "sizeInBytes": 3251, 
    },
     "latest": { 
        "content": "https://api.orderful.com/v3/transactions/123/content", 
        "validationStatus: "VALID", 
        "sizeInBytes": 3251, 
    },
}

Calling the content link will return you the content in its present JSON form:

content-type:application/json 
{  
    "transactionSets": [{
    ...
    }] 
}

And in the future, in newly-supported data types:

content-type: text/csv
invoiceNumber,456
invoiceDate,03MAR2021

More details can be found in the API reference documentation.