Important change to API2 contract

There is an important, breaking change coming soon to the contract for Version 2 of our Test API that we want to alert users to regarding the callbackUrl parameter.

Per the current documentation, callbackUrl is “(an)URL at which results will be POSTed to when testing has been completed”. Real-world usage shows that this feature could be improved and, while we normally avoid breaking changes, we’ve decided to do so in this case in order to avoid confusion for future users of the API. The following details what will be changed:

  1. The callback will be run twice: when the initial POST is made to the API and when the accessibility testing is complete. (Though not documented, this is happening now)
  2. callbackUrl is going away and will be replaced with callback
  3. callback must be an object. For example:

    "callback": {
        "url": "http://www.foo.com",
        "method": "POST",
        "headers": {
            "X-My-Header": "Value here"
        }
    }
    

  4. callback, if supplied, must be an object. If it isn’t an object, the API will return a 400 response
  5. callback, if supplied, must contain url. All other properties
    are optional
  6. If callback.method is not supplied, it will default to POST
  7. callback.method will support POST, PUT, PATCH, and DELETE methods.
  8. If Content-Type header is not supplied, we will default it to application/json

If you’re currently using callbackUrl in your API2-consuming code, the only thing you need to change is:

Before:
"callbackUrl": "https://foo.com"
After:
"callback": { 
    "url: "https://foo.com"
}

We anticipate that these changes will be deployed to production in one week, however the timeline depends on changing some of our own existing code for other parts as well in order to support this. To be notified when these changes are deployed to production, give us a shout at talktous@tenon.io

Start your free trial of Tenon today!