V3 Get Transactions endpoint change

This change comes with a helping of humility. We're 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.

The path forward is to maintain our JSON-first API but separate the content out into its own endpoint which can support any format. Now the message portion of the GET /v3/transactions/:id response will look like this:

"message": {
		"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