Why does this API include a static "kind" parameter in the request and response?

Within the request and response you send it does not immediately make sense, but I'll give a simpler example. Imagine we'll have a pizza-ordering system, that allows us to order either pizza's (with extra toppings) or soft-drinks (potentially super-sized). To implement our service, we could format it like this:

{ drinks: [{ brand: 'pipsi', size: 'large'}, { brand: 'cako loca', size: 'small' }], pizzas: [{ name: 'peperoni', toppings: 'mozarella'}] } 

however, this quickly becomes cumbersome when we have many kinds of pizza's, drinks, desserts, etc. etc. Instead, we want to give some class to our little API. We could classify each of these in two different kinds: 'PizzaData' and 'SoftDrinkData'.

Now the parts of our order can be ordered in any order, and we even have the option to add versions of our API to specific subparts. It's also easier to break our message apart and send it to separate places and have those places figure out how to handle it. Lets see how it looks like now:

[ { kind: 'SoftDrinkData', brand: 'pipsi', size: 'large' }, { kind: 'SoftDrinkData', brand: 'cako loca', size: 'small' }, { kind: 'PizzaData', name: 'peperoni', toppings: 'mozarella' } ] 

If our data-processors would introduce a new Pizza-type (say, you can specify the shape), you can add an extra version:

[ { kind: '[email protected]', name: 'Quatro Stagioni', toppings: 'salami', shape: 'triangular' } ] 

Old systems would now start to complain because they don't know how to handle '[email protected]'. That would be good, since you don't want the customer to get a round pizza. He ordered a triangular one after all. However, all other data can still be processed, so we can intermingle new and old systems together and we don't have a 'big bang'-moment when a new version of the API comes out.

Most JSON-libraries map the JSON data to instances of classes of an object-oriented language. The library needs to know which class to map to, so adding this extra data helps the library to map it to the right class, instead of relying on the location within the JSON tree.