Uber Hypermedia format

[mca]

/* pardon the cross-posting */

I just published a first working draft of a new hypermedia format I am (humbly) calling "Uber Hypermedia"[1]. I'm maintaining it in github[2] where you can post issues, clone/PR, etc. if you like.

It is designed to be *very* minimal. It has only three elements, 11 attributes, and seven reserved strings.

Here is some text from the opening:

<snip>

The Uber message format is a minimal read/write hypermedia type designed to support simple state transfers and ad-hoc hypermedia-based transitions. This document describes both the XML and JSON variants of the format and provides guidelines for supporting Uber messages over the HTTP protocol.

The Uber message model has a number of design goals:
- Keep the message structure as lean as possible.
- Support all the H-Factors [HFactor] in hypermedia controls.
- Be compatible with multiple protocols (e.g. HTTP, CoAP, etc.)
- Maintain fidelity for more than one base message format (XML, JSON, etc.)

</snip>

I'm looking for any/all feedback here or in the repo space.  Thanks in advance.

[1] https://rawgithub.com/mamund/media-types/master/uber-hypermedia.html

[2] https://github.com/mamund/media-types

mca

+1.859.757.1449
skype:mca.amundsen
http://amundsen.com/blog/
http://twitter.com/mamund
https://github.com/mamund
http://linkedin.com/in/mamund

[Kijana Woodard]

Thank you for cross-posting since I'm apparently not on the "other list".

What is the other list?

--
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/groups/opt_out.

[mca]

LOL!

i posted to hypermedia-web, api-craft, and rest-discuss.

enjoy!

mca

+1.859.757.1449
skype:mca.amundsen
http://amundsen.com/blog/
http://twitter.com/mamund
https://github.com/mamund
http://linkedin.com/in/mamund

[Mark Hildreth]

How do you see using this media type to reference vocabularies like schema.org? Let's say I want to use this to define a blog post. Would I do the following?

{

    "uber" : {

        "version" : "1.0",

        "data" : [

            { "rel" : "profile", "url" : "http://alps.io/schema.org/BlogPosting.xml" },

            { "rel" : "collection", "url" : "http://juliet.example/blog" },

            {

                "data" : [

                    { "name" : "author", "value" : "http://juliet.example/about" },

                    { "name" : "datePublished", "value" : "2014-02-28T23:00Z" },

                    { "name" : "text", "value" : "O Romeo, Romeo! wherefore art thou Romeo?" }

                ]

            }

        ]

    }

}

In this case, because I used the profile for BlogPosting, the "author", "datePublished" and "text" data values should properly be seen as the attributes for that schema, correct?

Another question: in the examples, you have the root "uber" element with the "data" list containing a single element with the "root" id. What is the purpose of this "root" element? Why not collapse the second-level "data" element into the first-level "data" element (like I've done in my example above)?

Thanks

[mca]

Mark:

Good points.

yes, I think using the schema.org as a reference is a good idea. I see you used the alps,io link. there needs to be a mapping guide for alps <-> uber for consistent implementation. for example, i agree that, for Uber, the "name" attribute is the proper mapping of alps id. also, it'd proly be best to use a JSON representation of the alps. document - I know that's now available on the site yet, tho (another task i should get around to soon!).

yeah, that example is kinda odd, i guess. the "root" data element is nothing special, just an example. there is no need for it in the spec, just a representation i built up on the fly. i proly need to put together a section of "canonical" examples that are more helpful (an idea i got from @inadarie). 

feel free to suggest some examples along these lines.

does this sound good?

mca

+1.859.757.1449
skype:mca.amundsen
http://amundsen.com/blog/
http://twitter.com/mamund
https://github.com/mamund
http://linkedin.com/in/mamund

[Mark Hildreth]

Mike,

The "mapping guide" would need to be part of the Uber spec (I believe similar to how JSON-LD has "@context"), correct? Is this a direction you see Uber taking?

I was just about to reply before you sent your e-mail that I had figured out the second question on my own. I was not looking closely enough at the resource, and mistakenly thought that we were looking at the representation for the "http://example.org/list/" resource, when really it was the "http://example.org" resource. If it were truly looking at "http://example.org/list/", it would make sense to have a similar-looking document but without the "root" element.

Thanks

--
Mark Hildreth

[mca]

yeah - Uber should proly host the mapping guidance. i posted a sample mapping document in the ALPS repo here:

https://rawgithub.com/alps-io/misc-docs/master/alps-to-html.html

not sure i follow on the resource representations, but i suspect that is proof the examples are a bit too vague ;)

mca

+1.859.757.1449
skype:mca.amundsen
http://amundsen.com/blog/
http://twitter.com/mamund
https://github.com/mamund
http://linkedin.com/in/mamund

[Pedro Santos]

Hello,

This may be a dumb question but why the "root" key in the JSON document?

I understand that a xml response must have a root element, but that's not needed in JSON... is it for consistency between the XML and JSON representations? or because of the "protocol independence" goal?

I ask because in theory isn't it the Media-Type's job to define what kind of message ("uber") and what version ("1.0") ? Isn't it redundant to include that information again inside the message itself? (again I maybe skewed torwards thinking in an "HTTP mindset")

Also if I understand correctly, although the data element is an array, the first data element in a document can only have 1 element right? The fact that that data id is a document wide identifier implies that there can be only one data element after the root "uber"... or am I looking at this wrong?

As far as I can see, there is not distinction made between what can be data "link" elements, and data "value" elements besides having (or not) the "rel" and "value" attribute present right? (regarding links, shouldn't both attributes "rel" and "url" be required together? i.e. either both are present or neither are)

PS: If the <link> and <div> tag ever had a baby, that would be the <data> element no? =)

[sune jakobsson]

It is defined like that... http://json.org/

Sune

[Mark Hildreth]

Pedro,

I had the same question and thought I answered it myself. I look at the example in not-3am-eyes and realized that my answer is still not good enough. I agree that the "root" object should probably be. AFAIC, it should be...

{

  "uber" :

  {

    "version" : "1.0",

    "data" :

    [

        {"rel" : "self", "url" : "http://example.org/"},

        ...

    ]

  }

}

--
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/groups/opt_out.

--
Mark Hildreth

[mca]

yeah - that example is just random. the <data id="root"> is just a data element, nothing else. nothing there is about requirements, etc.

I'll remove that from the example since it is now obvious that ppl are reading more into it than i intended. 

my bad!

mca

+1.859.757.1449
skype:mca.amundsen
http://amundsen.com/blog/
http://twitter.com/mamund
https://github.com/mamund
http://linkedin.com/in/mamund

[Pedro Santos]

Again what is the reasoning behind having "uber" key and "version" attribute? Can a response have more that one data element after the root?

Wouldn't something like this be preferrable/simpler (assuming that the version and message format is conveyed via Media Type):

For XML

<uber>
  <data rel="self" url="http://example.org/" />
  <data name="list" rel="collection" url="http://example.org/list/">
    <data name="search" rel="search" url="http://example.org/search" model="{&title}" />
    (...)
  </data>
  <error>
    <data name="internal-error">q1w2e3</data>
    <data name="debug-data" url="http://example.org/debug/1" />
  </error>
</uber>

For JSON

{
  "id" : "root",
  "data" :
  [
    {"rel" : "self", "url" : "http://example.org/"},
    (...)
  ],
  "error" :
  {
    "data" :
    [
      {"name" : "internal-error", "value" : "q1w2e3"},
      {"name" : "debug-data", "url" : "http://example.org/debug/1"}
    ]
  }
}

[mca]

All:

I've removed the <data id="root"> from the nesting sample in the Uber document. it was just a sample created to show lots of nesting and seems that was lost in my docs. instead people where assuming this was some normative model all representations had to follow.

Hopefully, removing this top-level data element will clear things up a bit more ;)

thanks for all the feedback and keep it coming!

Cheers.

mca

+1.859.757.1449
skype:mca.amundsen
http://amundsen.com/blog/
http://twitter.com/mamund
https://github.com/mamund
http://linkedin.com/in/mamund

[Cédric Brancourt]

Hi Mike,

I am wondering what is the intent behind  "rel" : "http://example.org/rels/create",

In :

              {
                "name" : "create",
                "rel" : "http://example.org/rels/create",
                "url" : "http://example.org/people/",
                "model" : "g={givenName}&f={familyName}&e={email}",
                "action" : "append"
              },

I guess it may be related to the relation semantic, but given the current informations provided by uber, what should i expect to find if I get the "rel" resource ? 

I know this is just an example, but I am trying to figure how this is intended to be used.

[Felipe Sere]

HI Cédric,

There are two things in play here: documentation and namespacing.

The namespacing part is fairly simple: you don’t want your “rel” : “create” to collide with somebody else’s if they are not the same.

Well, you shouldn’t at least. I guess technically nothing will go horribly wrong if two APIs use “create”, but as long as two APIs do different things for the same “rel” somebody will be confused ;-) “Heeeey… why doenst “create” to do this in that? In YXZs API it does!”

And then there is the documentation part. You can very well have the real documentation behind such a link. A developer getting to know your API can see such a response and go “Hey! This might be what I am looking for. Let’s see what ‘create’ does and what restrictions it has”… and presto his in the documentation, at the right place with a certain mindset.

@Mike: Does that about cover it? :)

Felipe

[Steve Klabnik]

It should cover it, but there's also "because the spec says so." Those
are the reasons the spec says so :p

[Steve Klabnik]

(the spec being RFC 5988, not Uber Hypermedia)

[Irakli Nadareishvili]

To test-drive Uber (which I am increasingly becoming a fan of) I added Uber support to the FroYo API: http://api.froyo.io 

FroYo uses content negotiation, so you can use it:

1. from browser serving HTML (so humans can easily discover & browse)

2. using CURL and "application/vnd.amundsen-uber+xml" to serve XML flavor of Uber

3. using CURL and  "application/vnd.collection.doc+json" to serve JSON flavor of CDoc.io

I think it actually works :)

Irakli

[mca]

Wow! sweet! you win that prize for the first server that recognizes the Uber identifier in the accept header!

BTW - I notice that the root resource for the Uber representation has some bugs in the URLs ("/apod" for names and "/names" for password):

<uber version="1.0">

  <data id="affordances" name="Froyo Utility API" rel="collection">

    <data name="APOD"

        rel="urn:froyo_io:query:apod:today"

        url="/apod" />

   

    <data name="Random name generator"

        rel="urn:froyo_io:query:names"

        url="/apod"

        model="?gender={gender m/f}" />

   

    <data name="Random password generator"

        rel="urn:froyo_io:query:pwd"

        url="/names"

        model="?length={numerical value}" />

  </data>

</uber>

thanks.

mca

+1.859.757.1449
skype:mca.amundsen
http://amundsen.com/blog/
http://twitter.com/mamund
https://github.com/mamund
http://linkedin.com/in/mamund

--
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.

[mca]

Irakli:

yep - the fix looks fine. thanks

<uber version="1.0">

  <data id="affordances" name="Froyo Utility API" rel="collection">

    <data name="APOD"

        rel="urn:froyo_io:query:apod:today"

        url="/apod" />

   

    <data name="Random name generator"

        rel="urn:froyo_io:query:names"

        url="/names"

        model="?gender={gender m/f}" />

   

    <data name="Random password generator"

        rel="urn:froyo_io:query:pwd"

        url="/pwd"

        model="?length={numerical value}" />

  </data>

</uber>

BTW - I love the way you designed the linked resources to point back to the "home" page, too.

<uber version="1.0"> <data rel="urn:froyo:apod:val" name="NASA APOD Photo" transclude="true" value="http://apod.nasa.gov/apod/image/1403/FuscoSeaIsleCityVenusMilkyWayRise900.jpg" /> <data name="Home" rel="home" url="/" /> </uber>




mca

+1.859.757.1449
skype:mca.amundsen
http://amundsen.com/blog/
http://twitter.com/mamund
https://github.com/mamund
http://linkedin.com/in/mamund

[wiki1000]

Hello, sorry for asking this way, but you certainly have rationales for the need of a format,

rather than some conventions leveraging HTTP headers, just like Mark Nottingham (seems to) does.

I have very recently discovered (following one of your hints) the Link-Template, accept-post, and profile

conventions. There are certainly good reasons to not following this way. 

Another point is the use of JSON. RDFa is very good at reusing html to encode any kind of typed object

graph;why not using that ? 

[Thomas Lörcher]

Hi Mike,

thx for your great work concerning REST / HATEOAS. Appreciate it. 

Today I read your actual draft of UBER.

Some recommendations for additions or changes:

1. I think you have in mind URL Templates, but I think you should emphasize it in the document (probably by introducing a PUT / replace section).
   
2. Please introduce the counterpart of the HTTP HEAD method. I think it's pretty useful (compare caching, ...). Probably you could name it info or sth. similar 
3. Probably you should introduce an example of a append / replace model 
4. I'd suggest (but that's my humble opinion) to not use the HTTP-dependent read model using &..=...&..=.. I think the model "key":"value", "key2":"value" is more ubiquitous despite used with JSON
5. I'd suggest to have no <data>-element for all elements using XML. It's easier for a client to work with distinct XML-elements (besides being more readible) for example using XPat

Overall it promises to become a great hypermedia-format.

Regards,
Thomas Lörcher, @0ldJimmy