Breaking Change: Object Collections

Dan Bowman

During our SKY API Tech Preview 2.0 period, the API will be subject to a few periodic breaking changes as we refine and improve it. We wanted to let you know in advance that one of these changes is scheduled to be introduced in the next day or so. 

We will be standardizing the shape of our responses that return a collection of objects. This standardization will allow us to be consistent across each endpoint as well as to facilitate some future enhancements around pagination within those endpoints. The new representation of a collection will be a JSON object with two properties, a count which represents the total number of records meeting the criteria and a value property which represents the array of items for the current paged response.

How a collection response is formed today (Phones used as an example):

{

    "phones": [

        {

            "id": "95",

            "type": "Home",

            "number": "303-997-3301",

            "do_not_call": false,

            "primary": true,

            "inactive": false

        },

        {

            "id": "330",

            "type": "Home",

            "number": "(312) 997-3301",

            "do_not_call": false,

            "primary": false,

            "inactive": false            

        }

    ]

}

 

How the response will be formed after release:

{

    "count": 10, // total number of elements in the collection

    "value": [   // collection of items included in this response

        {

            "id": "95",

            "type": "Home",

            "number": "303-997-3301",

            "do_not_call": false,

            "primary": true,

            "inactive": false

        },

        {

            "id": "330",

            "type": "Home",

            "number": "(312) 997-3301",

            "do_not_call": false,

            "primary": false,

            "inactive": false            

        }

    ]

}

Please refer to the March 31st Changelog post in the SKY API Developer Portal for more details.