json hypermedia type for mobile devices

[Maciej Jaśkowski]

Hi there,

my friends and I, we have come up with a new json hypermedia type inspired by collection+json and yet somewhat different. Or as I prefer to say: we turned collection+json upside down. 

I would love to hear your honest opinion on four fields:

1. what's your "user experience"? Do you find it comprehensible and simple [1]?

2. do you find it as expressive as collection+json or hal is?

3. would you find it useful in other domains then mobile applications?

4. do you find any risks of using this hypermedia type?

5. have you seen/conceived similar hypermedia type?

Instead of providing a detailed protocol description (which is work in progress anyway) I'd like to share a thought or two and point to an example. 

Please, find the thoughts below and the example here: [2].

Best,

Maciej Jaśkowski

And now to the hypermedia type itself. 

One of the key requirements is (of course) that the client's experience is smooth or that he can't notice that the data is being fetched from server. 

Therefore, we thought at first we would use collection+json and enhance it a little bit: we wanted to add a "prefetched" field to each "link" object (example: [3]).

That seemed fine at first but the hypermedia type got uglified. It also "feeled" not right somehow. So we finally came up with a completely different solution (example: [2]). The final outcome is that if one asks for a resource, say GET / then in the response he will get for example:

{

  "href": "/",

  "cache": {

     "/": {

       "collection": [ /* actual collection */ ],

       "links": [ 

          {

             "rel": "accounts",

             "href": "/accounts"

          },

          {

             "rel": "users",

             "href": "/users"

          }

       ]          

     },

     "/users": {

       "collection": [ /* actual collection */ ],

       "links": [ /* links */ ]

     }

  }

}

The promise given to the API consumer is that if he asks for GET / and gets some additional resource in response (e.g. "/users") then the subsequent GET /users would yield exactly the same result.

[1] Please note: I know it might be hard to read at first but easy != simple

[2] api-browser: namu-api-browser.herokuapp.com/index2.html

api root endpoint: namu2.apiary.io

Please note: apiary serves here as a service mock so the data might and will be incosistent

[3] api-browser: namu-api-browser.herokuapp.com/index.html

api root endpoint: namu.apiary.io

Please note: this ain't exactly collection+json++ but is heavily inspired on it.

[Jan Kronquist]

Hi

I have used embedded resources in application/hal for similar purpose, both in mobile and single page applications. There are a couple of things I like better with hal:

* the fact that the server is allowed to use partial or inconsistent representations in the embedded resources as this gives me more freedom and is especially useful for collections. Notice that I may return the complete representation if the use case has that requirement.

* using rels instead of URLs and self-links to support user-agent caching

/Jan

[Maciej Jaśkowski]

Thanks for your input Jan!

On 22 April 2014 13:30, Jan Kronquist <jan.kr...@gmail.com> wrote:

Hi

I have used embedded resources in application/hal for similar purpose, both in mobile and single page applications. There are a couple of things I like better with hal:

* the fact that the server is allowed to use partial or inconsistent representations in the embedded resources as this gives me more freedom and is especially useful for collections. Notice that I may return the complete representation if the use case has that requirement.

Aha, I will consider how one could incorporate this idea

 

* using rels instead of URLs and self-links to support user-agent caching

What do you exactly mean? Could you give an example?

Best,

Maciej

 

--
You received this message because you are subscribed to the Google Groups "API Craft" group.
To unsubscribe from this group and stop receiving emails from it, send an email to api-craft+...@googlegroups.com.
Visit this group at http://groups.google.com/group/api-craft.
For more options, visit https://groups.google.com/d/optout.

[Jan Kronquist]

* using rels instead of URLs and self-links to support user-agent caching

> What do you exactly mean? Could you give an example?

The idea is really simple, perhaps so simple I will fail to explain it :-)

Abbreviated from http://stateless.co/hal_specification.html

{
    "_embedded": {
        "ea:order": [{
            "_links": {
                "self": { "href": "/orders/123" },
                "ea:basket": { "href": "/baskets/98712" },
                "ea:customer": { "href": "/customers/7809" }
            },
            "total": 30.00,
            "currency": "USD",
            "status": "shipped"
        }]
    }
}

if a user-agent want to follow the "ea:order" link, it obviously does not need to do any requests as all data is already embedded in the original message. However, if the user/programmer for some weird reason directly references "/orders/123", then the user-agent understanding application/hal might also return the embedded resource. Keep in mind that the programmer must be able to check if the resource was retrieved from the server OR from an embedded resource since embedded resources might be partial. 

In my latest project we wrote a small wrapper on top of Angular's Http service to make it aware of application/hal and embedded resources.

/Jan

On Wed, Apr 23, 2014 at 11:03 AM, Maciej Jaśkowski <maciej.j...@gmail.com> wrote:

Thanks for your input Jan!

On 22 April 2014 13:30, Jan Kronquist <jan.kr...@gmail.com> wrote:

Hi

I have used embedded resources in application/hal for similar purpose, both in mobile and single page applications. There are a couple of things I like better with hal:

* the fact that the server is allowed to use partial or inconsistent representations in the embedded resources as this gives me more freedom and is especially useful for collections. Notice that I may return the complete representation if the use case has that requirement.

Aha, I will consider how one could incorporate this idea

 

--
You received this message because you are subscribed to a topic in the Google Groups "API Craft" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/api-craft/kDHBAqykNE4/unsubscribe.
To unsubscribe from this group and all its topics, send an email to api-craft+...@googlegroups.com.