Collection data type serialization

[Jiaudheen Abdul Malick]

Hi,

 I wish to have your advice on exposing collection data from the APIs. Its recommended in oada standard that,  

for example.  /bookmarks/irrigation/machines . .should have response some thing similar to, 

 

{

   “_id”: “20kldfjwie”,

   “_rev”: “3-kdfj02klsjdf”,

   “_meta”: { 

      “_metaid”: “20kldfjwie”,

      “_rev”: “1-we8dfoij23l”

   },

   “name”: “irrigators”,

   “list”: {

      "<device-id-1>": {

         "_id": "abc123", _rev: “1-53554t4yh4v2302”

     },

     "<device-id-2>": {

        "_id": "def456", _rev: “4-dfg3rthdfbe5t”

     }

  }

}

and then /bookmarks/irrigation/machines/list/<device-id-1> would be resource /resources/abc123. 

Normally in.net an object collection are exposed either by indexes or key-value pair which are built in...

sample json: 

{

   “_id”: “20kldfjwie”,

   “_rev”: “3-kdfj02klsjdf”,

   “_meta”: { 

      “_metaid”: “20kldfjwie”,

      “_rev”: “1-we8dfoij23l”

   },

   “name”: “irrigators”,

   “list”: [2] {

      0: {

            key: "<device-id-1>",

            _value : {

                   "_id": "abc123", _rev: “1-53554t4yh4v2302”

               }

         },

     1: {

            key: "<device-id-2>",

            _value : {

                   "_id": "xyz123", _rev: “2-53554t4yh4v2302”

               }

         }

  }

}

where the key will be the resource key and by searching   list[<device-id-1>]  would find {  "_id": "abc123", _rev: “1-53554t4yh4v2302”}

using this resource key "<device-id-1>"  in /bookmarks/irrigation/machines/list/<device-id-1> would retrieve the same as 

/resources/abc123.

Queries :

1. I would like to know whether this key-value pair will get serialized in the test suit and in any of non .net client application.

2. If not i would like to know your recommendation in this and the data type you use in the test suit.

3. I also wish to know the language used to build the test suit.

Thanks,

Jiaudheen A

[Andrew Balmos]

Jiaudheen,

On Wed, Oct 7, 2015 at 9:49 AM, Jiaudheen Abdul Malick <jiaudheen@gmail.com> wrote:

1. I would like to know whether this key-value pair will get serialized in the test suit and in any of non .net client application.

I have no experience with .net and I'm not completely following. The second example is not valid JSON. However, I believe your understanding of what an OADA API should do (the first example) is correct.

As long as the API response follows the URL <-> JSON document mapping, that is the URL matches the nesting of the JSON property names (JSON Pointer), then it's following OADA. That said, certain JSON structures may or may not be required by a particular media type. In your second example (with the extra [2] removed) you could use the url: /bookmarks/irrigation/machines/list/0/_value to get the resource link but I doubt that follows the JSON schema of the mediatype you are implementing.

2. If not i would like to know your recommendation in this and the data type you use in the test suit.

I guess you need some sort of logic to remove the Collection noise. I don't really understand the .net data types but after some googling maybe a System.Collections.Generic.Dictionary<TKey, TValue> would be a better? Not sure how that serializes though.

3. I also wish to know the language used to build the test suit.

We use node.js (javascript). You can find the current version of the compliance tests here: https://github.com/OADA/oada-conformance. They are still being developed but much of the main tests are there. You will need to configure config.js for your API.

Andrew

[Aaron Ault]

Just to add a few comments to Andrew's answer: the test suite will not be serializing or transforming the responses.  It will simply check that, given a particular content-type returned in a response, that the response body validates using a validator for that particular media type, if one is known.  In this case, if the JSON given in your first example is returned, then it will validate.

If the not-valid-JSON of your second response is returned (as Andrew mentioned, the "[2]" after "list:" isn't valid JSON), it will not validate.  If the "[2]" is removed, it will be valid JSON but still will not validate since the content-type of "application/vnd.oada.irrigation.machines+json" says that the objects inside the "list" key should have keys named "_id" and "_rev", and in your second example those objects contain "key" and "_value" keys instead.  

If the only way you can construct the JSON response is to have .NET serialize an existing object in a way which puts in all the extra "key" and "_value" keys, then probably the easiest answer is to just let .NET construct the response it wants, then pass that through a global sanitizing function that finds any "key" and "_value" pairs and replaces them in the response such that a new key is made with the value at the "key" key, and it's value is the value of the "_value" key.  It seems like I said "key" entirely too many times in that sentence :).

The test suite isn't written in a typed language (javascript), so it doesn't have any particular type assigned: it's just a javascript object.  In this case, it will use JSON schema to validate the javascript according to a schema definition.

It's also worth clarifying that the test suite only interacts with an OADA API implementation via remote HTTP calls, so there is no need or benefit from it being written in the same language as that used to implement the API: i.e. it doesn't matter if the API under test is implemented in .NET and the test suite is implemented in Javascript.

Thanks

Aaron