0

I am looking at the Google QPX Express API and noticed that each group of parameters includes a kind parameter that is set to a specific string. For example, on the request:

{
  "request": {
    "passengers": {
      "kind": "qpxexpress#passengerCounts",
      "adultCount": integer,
      "childCount": integer,
      "infantInLapCount": integer,
      "infantInSeatCount": integer,
      "seniorCount": integer
    },
    "slice": [
      {
        "kind": "qpxexpress#sliceInput",
        "origin": string,
        "destination": string,
        "date": string,
        "maxStops": integer,
        "maxConnectionDuration": integer,
        "preferredCabin": string,
        "permittedDepartureTime": {
          "kind": "qpxexpress#timeOfDayRange",
          "earliestTime": string,
          "latestTime": string
...

The response includes a kind as well:

{
  "kind": "qpxExpress#tripsSearch",
  "trips": {
    "kind": "qpxexpress#tripOptions",
    "requestId": string,
    "data": {
      "kind": "qpxexpress#data",
      "airport": [
        {
          "kind": "qpxexpress#airportData",
          "code": string,
          "city": string,
          "name": string
...

What's the point of this parameter? Is this type of thing important to include in a well-designed API?

1

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: 'PizzaData@v2.0', name: 'Quatro Stagioni', 
    toppings: 'salami', shape: 'triangular' } ]

Old systems would now start to complain because they don't know how to handle 'PizzaData@v2.0'. 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.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.