Designing JSON representations

[Jack Snow]

I am reading RESTful Web Services Cookbook and there's what they have to say when it comes to designing JSON representations:

 

In each representation, include a self link to the resource and include identifiers for each of the application domain entities that make up resource.

 

And here's a sample:

{
   "name":"John",
   "id":"urn:example:user:1234",
   "link":{
      "rel : "      self",
      "href":"http://www.example.org/person/john"
   },
   "address":{
      "id":"urn:example:address:4567",
      "link":{
         "rel : "         self",
         "href":"http://www.example.org/person/john/address"
      }
   }
}

Notice the "id", "link", "rel" and "href". Do you guys actually do this for production RESTful APIs? I personally find it to be a bit verbose. For example, if I am returning a list of the user's friends, then I might provide a link to the friend's profile, but that is all. What do you guys think? Do you think it's necessary to provide the link meta data? It reminds me somewhat of WRML which I feel is overkill.

 

[Jerome Louvel]

Hi Jack,

The goal of this best practice is to make your web API more hypermedia driven (HATEOAS), but in practice this isn't sufficient at all and it indeed brings some verbosity.

Personally, I would recommend a self link only if there is a good chance that the representation can be saved/used beyond the HTTP conversation and needs to be somewhat self-consistent to be able to resolve relative links (like a base reference).

Thanks,
Jerome
--
http://www.restlet.com

http://twitter.com/#!/jlouvel

2013/1/4 Jack Snow <infec...@gmail.com>

 

--
You received this message because you are subscribed to the Google Groups "API Craft" group.
To unsubscribe from this group, send email to api-craft+...@googlegroups.com.
Visit this group at http://groups.google.com/group/api-craft?hl=en.
 
 

[Glenn Block]

I disagree that is the goal. Hypermedia is a means to end, not the end in itself. The advantage of the self link is it removes clients from hardcoding logic around creation of urls.The server offers them data and a link to find it. ATOM uses self links as an integral part, so it definitely works. As to whether it is overkill or not, Subbu the author of the book was an architect at Yahoo where they made Flickr etc, and this book is a compilation of the practices they used which granted was for very large scale API consumption.

Now whether you should use it is really up to you. You don't have to. If you are concerned about clients being too coupled to your API/urls or if you want to make it easier for newer consumers to navigate your API then this is an option.

[Jerome Louvel]

Hi Glenn,

Well each goal is a actually a mean to something else :) Being more hypermedia driven brings you closer to being RESTful and therefore closer to fully benefiting from REST properties, such as independent evolution of clients and servers. Unfortunately, just placing a self link in your representation doesn't make your clients really independent of your server.

Talking about large scale RESTful API consumption, the best example around is still HTML, which doesn't use self links that much AFAIK. 

Thanks,
Jerome
--
http://www.restlet.com

http://twitter.com/#!/jlouvel

2013/1/4 Glenn Block <glenn...@gmail.com>

[Glenn Block]

I don't think a single self link by itself makes your system more evolvale. It is a number of things together which lead to a more evolvale system. As to REST properties, REST is a series of constraints which provide a set of benefits, however systems can still benefit without adhering to all. And you may not need all.

I don't think using HTML is the best example because it is not a machine to machine interaction in it's conventional usage. Human beings navigate by clicking links or interacting with an app that uses code on demand for more sophisticated scenarios. The human doesn't couple to the uri.

In this case you have machines consuming the API, maybe many 3rd parties and the coupling is much more likely to be a concern.

[Glenn Block]

And evolvale is iPad's way of spelling evolvable :-)

[Jørn Wildt]

HTML doesn't have many "self" links, right, but instead they usually have many other similar links like "home" on each and every resource representation. "home" is valuable in human facing HTML - "self" can be valuable in machine-2-machine APIs. Same idea, slightly different purposes.

/Jørn

--

[Dietrich Schulten]

From the atom rfc:
"3. The value "self" signifies that the IRI in the value of the href
       attribute identifies a resource equivalent to the containing
       element."

I didn't find a compelling use case for self yet. If I understand it correctly, the href is not guaranteed to remain stable, so it doesn't safely identify an element for future sessions. And I did not see a case where it really made sense to retrieve a resource as a standalone representation which I already had in the current resource, where it might be part of a collection or attached to another object. It is not equivalent to home, since self must not point to a different resource. Has anyone actually used self for something in a client? I know atom requires it as a SHOULD and I am all for adhering to that, but what can a client really do with it?

Best regards,
Dietrich

--

[Glenn Block]

Well github uses it in their API and recommends you prefer links wherever they serve them and not hardcoding.

http://developer.github.com/v3/repos/#list-your-repositories

Clients of github use those links.

[Jerome Louvel]

I agree that you don't need to adhere to all REST principles to benefit from it.

As for HTML, it does rely on a M2M communication: between a web browser software/host computer and a remote web server. Most machines are controlled in one way or another by humans anyway, through a web browser UI, through a native mobile app, through an LCD screen and set of physical buttons and so on.

When you consider that the self link is already contained in the request URI, it does seem redundant info to me, and a machine can certainly remember this information along side the retrieved JSON representation if needed. If it is really more convenient to have it embedded/duplicated in the representation itself, then why not but doing it systematically really seems overkill.

Jerome
--
http://www.restlet.com

http://twitter.com/#!/jlouvel

2013/1/4 Dietrich Schulten <dietrich...@googlemail.com>

[Glenn Block]

We also do the same in our Azure Management APIS which are accessed by millions of HTTP clients.

On Friday, January 4, 2013, Dietrich Schulten wrote:

[Glenn Block]

Yes it has some m2m aspects but it doesn't arbitrarily navigate links other than say redirects. The human clicks the rendered link that is in the HTML.

In a mobile app, if I don't use links, I am hardcoding the logic.

As to the self link, if I am looking at a collection, then I do not know the uris off the children. I either have hardcoded logic how to get  to them, or I follow a link.

If I am talking about an individual item, it makes it easier to store / transfer the payload as it has all the information about where it came within. 

As to the cost, yes there is a cost, though in the scheme of things and with compression and such it's minimal.

[Jerome Louvel]

Agreed... though you can't discount web spiders too quickly, pure M2M :)

Cheers,

Jerome

2013/1/4 Glenn Block <glenn...@gmail.com>

--

[Glenn Block]

Definitely agree webspiders are pure m2m, but they don't hardcode uris, they just walk them right? ;-)

2013/1/4 Glenn Block <glenn...@gmail.com>

--

You received this message because you are subscribed to the Google Groups "API Craft" group.
To unsubscribe from this group, send email to api-craft+...@googlegroups.com.
Visit this group at http://groups.google.com/group/api-craft?hl=en.
 
 

[Dietrich Schulten]

as I said, I'm all for including it, it is a SHOULD after all. Constructing urls in the client from previously known url templates and using server ids for that is certainly not an option, and self makes that clear.
But what do the clients actually do with self? Ok, they could use it for bookmarking if they update bookmarks upon a 301. However, that is just a possible use case, I never really did that. Are there clients implementing use cases on the client side which *require* self?

[Jerome Louvel]

Like you, I'm all for using hyperlinks to point to other relevant resources exposed by the web API. No question about this best practice.

Self links just seem less useful in this regard. 

[Glenn Block]

Ok, let's take a scenario close to my heart, contact management.

My mobile contact management client returns a list of contacts. Now I go an want to edit one. What does the client do? It grabs the self-link and does a PUT.

Without that link, the client has to know how individual contact resource uris are formed right?

Imagine that same client works against diff back ends that return a familiar format of data. Now the same client can even operate against diff backends as it has no coupling to the uri.

--

[Glenn Block]

Personally I see less value in the self link for the collection itself, but much more value in links to the individual items.

[Mike Kelly]

On Fri, Jan 4, 2013 at 10:10 AM, Jerome Louvel <jlo...@restlet.com> wrote:
> Like you, I'm all for using hyperlinks to point to other relevant resources
> exposed by the web API. No question about this best practice.
>
> Self links just seem less useful in this regard.
>

You could argue that for the root resource you are representing that a
self link is redundant because it's probably duplicating the effective
request URI (or the URI in the Content-Location header). However, the
same is not true for embedded representations of related resources..
you need a way to indicate what their URI is (since it is embedded and
by definition has a different URI from the effective request URI).

I thought about this a lot when designing hal+json, and came to the
conclusion that even though it is arguably redundant to include the
self link for the root resource, it is still a good idea mainly
becuase:

- Client parsing libraries can deal purely in terms of JSON and do not
need access to some data structure representing the response/request.

- The way you represent a resource is consistent whether embedded or
not, and this is good because it's a simpler model and makes stuff
like server-side or edge-side includes possible.

there are probably other reasons they're just not coming to mind right now

Cheers,
M

[Dietrich Schulten]

Thank you for the eye-opener. I admit I did not consider other methods than GET for self. :-)

Best regards
Dietrich

[Glenn Block]

So you are saying you see value in links for child / related resources, but the self link for the main resource itself you think is redundant?

So for example individual contacts in the list of contacts having a self link is valuable, but not the collection?

[Glenn Block]

Glad I can help give some clarity. :-)

You are asking good questions. I am a big believer in know why we should do what we do, and not just because I read it hear or so and so told me I should.

Also your mileage my vary. I am not saying you MUST do this.....

--

[Jerome Louvel]

I fully agree for linking to child/sibling/parent resources, either partially represented in a collection resource's representation or just linked to. For me they are not 'self' links anymore but links to relative resources.

BTW, for those URIs it is interesting to rely on relative URI references based on the resource's URI (self), like relative links in HTML are resolved against the base document URI. That makes the representation more compact and readable.

I'm less sold out on the idea of duplicating info between request/response URI/headers and the representations for the sake of self-consistent representations. I'm afraid that we'll end-up with envelopes like SOAP, loosing too much of the value of web APIs : the HTTP protocol itself. Representations media types are only part of the story. 

Jerome

2013/1/4 Mike Kelly <mikeke...@gmail.com>

[Felipe Sere]

I'd add something to the actual structure of the links rather than their presence.

The way they are right now, find the right link is a more complicated than required. Plus you can only have one link.

I'd propose links like this:

{

    "name": "John",

    "id": "urn:example:user:1234",

    "link": {

        "self": {

            "href": "http: //www.example.org/person/john"

        },

        "family": {

            "href": "http://www.example.org/person/john/family"

        }

    }

}

The actual literal 'rel' is unnecessary and hiding it within an object makes finding the right 'rel' and then following href annoying.

This way, doing john.link.self.href will be null if 'self' does not exist.

You can extend it to add a 'type' and 'method' etc. attribute to the actual 'self' or 'family' object.

What do you guys think?

[Mike Kelly]

On Fri, Jan 4, 2013 at 12:47 PM, Jerome Louvel <jlo...@restlet.com> wrote:
> I fully agree for linking to child/sibling/parent resources, either
> partially represented in a collection resource's representation or just
> linked to. For me they are not 'self' links anymore but links to relative
> resources.

I find it's much easier to think about and model linking and embedding
as two different things. An embedded resource can be relative to the
'base' resource, this is something your API's format can and should
specify, e.g. this is a snippet showing how you can represent an order
and an embedded customer resource using hal+json:

GET /order/1

{
_links: {
self: { href: "/order/1" }
},
_embedded: {
customer: {
_links: {
self: { href: "/customer/1" }
},
name: "Bob",
age: 22
}
}
}

This embedded customer representation is consistent with its direct
representation:

GET /customer/1

{
customer: {
_links: {
self: { href: "/customer/1" }
},
name: "Bob",
age: 22

}
}

> BTW, for those URIs it is interesting to rely on relative URI references
> based on the resource's URI (self), like relative links in HTML are resolved
> against the base document URI. That makes the representation more compact
> and readable.

This is orthogonal to the current discussion around self links on the
base resource representation, and is down the processing rules of your
APIs format.

> I'm less sold out on the idea of duplicating info between request/response
> URI/headers and the representations for the sake of self-consistent
> representations. I'm afraid that we'll end-up with envelopes like SOAP,
> loosing too much of the value of web APIs : the HTTP protocol itself.
> Representations media types are only part of the story.

This has nothing to do with SOAP or undermining HTTP. It's about
making informed design decisions in an effort to optimise the
usability of an API, of which I gave two examples - what is it about
those two you disagree?

Cheers,
M

[Steve Klabnik]

For another use of self URIs: https://gist.github.com/3172911

[David Biesack]

We use it after querying/iterating resource collections; each element in the collection rep is a (summary) representation with a self link which the client can use to obtain the complete representation.

[chris...@gmail.com]

On Fri, 4 Jan 2013, Jerome Louvel wrote:

> I'm less sold out on the idea of duplicating info between request/response
> URI/headers and the representations for the sake of self-consistent
> representations. I'm afraid that we'll end-up with envelopes like SOAP,
> loosing too much of the value of web APIs : the HTTP protocol itself.
> Representations media types are only part of the story.

I have similar fears but unfortunately they are hard to articulate
as anything other than smelling bad smells.

For me the notion that adding more is somehow going to make things
less complex is an obvious red flag that deserves some attention but
that's about as far as I can get.

I suspect a lot of it is related to fairly fundamental attitudes
towards tools and tool building, something like craftsmanship versus
engineering. Yes, you'll get a more correct solution for all the
known contexts by using good engineering but if you're more
interested in generating, exploring or enabling new contexts the
kind of engagement that goes hand in hand with craftmanship may be
very powerful.

For a lot of hypermedia lovers that last paragraph will probably
grate: hypermedia is supposed to enable a measure of
context-freeness for agents. It probably does, but what does it do
for crafty engagement?

--
Chris Dent http://burningchrome.com/
[...]

[Steve Klabnik]

> For a lot of hypermedia lovers that last paragraph will probably
> grate: hypermedia is supposed to enable a measure of
> context-freeness for agents. It probably does, but what does it do
> for crafty engagement?

Just try it for a while. I find that not needing to construct a URL by
hand is suuuper convenient.

[Mike Kelly]

I think, at least in this particular case, that "conflict" is almost
entirely dreamt up.

There is no conspiracy here to create envelopes or generally undermine
HTTP.. there are practical reasons in this specific case (I outlined
two) why the redundancy of a self link in the body is a worthy
trade-off.

Not sure why we're talking about SOAP or needing to discuss
engineering vs craftsmaship.

[mca]

There's another way to view the trend to adding more information in messages...

One of the ideas behind the use of hypermedia controls within responses is to move some things that now often reside in client source code out and into the message. 

The simplest example of this is URI tracking and construction. In RPC-style Web APIs, devs are provided a list of URIs along associated rules for creating more of them, knowing which protocol methods are valid for each URI and which bodies and query params are valid for each. Devs are expected to load up (into source code or via configs) this information, create code that will fashion bodies and query strings, and even know _when_ executing each request is valid (be sure to login first, don't try to add a user-address before adding a user, etc.).

Hypermedia-style Web APIs take a different route. They describe a standard for identifying URIs ("look for the URI that has the rel='home' identifier..."), for constructing them ("we use RFC 6570 to define query templates, XForms to define body templates..."), and for knowing when these transitions are valid ("if the template/form does not appear in the response you can assume that this particular transition is not valid at this time...").

Yes, this means devs create code to recognize, parse, and (in some cases) activate these links/forms; that is "new" code. But the good news is (esp. for registered types like HAL, Cj, Siren, etc.) there are libs that already exist for this. Even better these libs reduce the the hand-coding for *all* apps that support these hypermedia-based media types.

We already accepted this "I'll just use a lib" POV for serialization. Few devs hand-roll their payload-to-local-object-graph mapping anymore - they pull a lib and use that. What I see happening now is merely a trend to push that pattern further along into additional aspects of the dev experience.

There are other reasons to adopt a hypermedia-style approach for APIs, but I think URI/payload handling is the one easiest to grok at the outset since so much of what we do as devs is tied to this work when building client apps.

mca

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

--
You received this message because you are subscribed to the Google Groups "API Craft" group.

To unsubscribe from this group, send email to api-craft+unsubscribe@googlegroups.com.

[Mike Kelly]

On Fri, Jan 4, 2013 at 3:02 PM, mca <m...@amundsen.com> wrote:
> The simplest example of this is URI tracking and construction. In RPC-style
> Web APIs, devs are provided a list of URIs along associated rules for
> creating more of them, knowing which protocol methods are valid for each URI
> and which bodies and query params are valid for each. Devs are expected to
> load up (into source code or via configs) this information, create code that

> will fashion bodies..

I think a lot of people find the point about "fashioning bodies" hard
to swallow when talking about APIs, because the difference between
"fashioning a collection of state to chuck at a form" is not very
different from "fashioning a collection of state and serialising it
into json" other than the former being significantly more complicated
because it now involves the indirection of form processing rules!

It seems like a lot of complexity just to be able to rename or omit
parameters on the client before they hit the wire, particularly when
it's a problem that's so trivially dealt with on the server side
anyway.

Cheers,
M

[mca]

do you think fashioning bodies is more complex than fashioning query strings?

i certainly agree that the function myStuff.toJSON() is easy. is it "not complex", too?

what about  myStuff.toFormURLEncoded()? or myStuff.toURITemplate()? easy? complex?

mca

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

M

--
You received this message because you are subscribed to the Google Groups "API Craft" group.

To unsubscribe from this group, send email to api-craft+...@googlegroups.com.

[chris...@gmail.com]

On Fri, 4 Jan 2013, Mike Kelly wrote:

> Not sure why we're talking about SOAP or needing to discuss
> engineering vs craftsmaship.

Presumably to have a discussion? That's what this is after all, a
discussion list. I made it pretty clear in my message that my
concerns are ambiguous and the hope is that by _discussing_ them
I'll gain some insight. I contributed in the first place because
Jerome has related but different concerns which are similarly
ambiguous. So a sort of feeling around in the dark for common ground
sort of thing. Such things are just as useful (for some of us?) as
practical solutions.

I hope I'm not wrong in my assumption that pursuing such discussions is
in scope? Clearly there are a lot of opinions and a lot of techniques
and as yet no one true and clear way (thank goodness).

And, really, c'mon: The list is named api-_craft_, of course I'm
going to bring up craftsmanship.

I, personally, have little against links in representations, for the
most part. Useful indeed. Where I get sketchy is when things start
feeling over-engineered, too verbose for the sake of non-human
agents. I've yet to identify the boundary point between okay and non
okay and why it feels like a problem. I'd like to.

Thus the comment.

Case in point: I look at the HAL spec and I think "I get it, I ought to
think this is cool, but it is giving me the squirms." Assuming you're
the same Mike Kelly who wrote it you might find this reaction useful to
plumb if your hoping to convince a wide audience of the efficacy of your
stuff. Jerome's reaction:

> However, by not going far enough in the discoverability front
> (semantics of links, structure of data) and form control (as you cover
> in the FAQ), it doesn't bring, IMHO, enough value to compensate the
> extra processing cost and complexity.

is not the same as mine. Mine's more like "aw, dude, can you turn
down the saturation, too much noise".

I fully admit that's rather strange, but it is there nonetheless.

mca's post is a nice overview of "why hypermedia" and "why more in
messages". I suspect a part of my issue is that I _do_ tend to read
and write (mostly read) a lot of JSON fairly close to wire and so
much of the additional syntax for things like HAL or Siren[1] are in my
way, despite being able to acknowledge that when augmented with the
proper library, code could like it very much.

So the general observation is something like: Aw hell, another layer
of indirection. The general concern is something like: That's bit me
before.

Thanks for enabling me to get that off my chest. I won't quite say
allowing or encouraging.

[1] I can report that HAL gives me fewer squirms than Siren.

[Mike Kelly]

I think that URI templates are far more capable than just query
strings. URI templates are basically just a uniform way of turning a
data-structure like a JSON object into most URI structures you could
care to imagine.. form URL encoding is not really in the same ballpark
there right? or are you claiming they are equivalent or that the extra
capabilities of URI templates are not worth the gains in the range of
URI they can represent?

JSON is a ubiquitous and relatively simple message format, so yes I
think it's fair to say it sits low on the complexity continuum.

--
Mike

http://twitter.com/mikekelly85
http://github.com/mikekelly
http://linkedin.com/in/mikekelly123

[mca]

not making any claims at all here, just asking about your use of "easy" and "complex" by way of offering some examples.

IOW, which of the examples i offered at *not* easy? which are complex?

Cheers.

mca

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

[Mike Kelly]

On Fri, Jan 4, 2013 at 4:05 PM, mca <m...@amundsen.com> wrote:
> not making any claims at all here, just asking about your use of "easy" and
> "complex" by way of offering some examples.
>
> IOW, which of the examples i offered at *not* easy? which are complex?
>

easy:

standard_http_client.post(url: create_widget_url, json: widget)

complex:

form_processing_http_client.traverse_via_form(form_name:
"create_widget", state: widget)

[mca]

neither of which i offered up.

but thanks.

mca

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

[Mike Kelly]

Have you read the hal+json spec? It's not very long or complex. It
basically just drops two *optional* properties into your normal json
i.e. _links and _embedded.

If we want to build re-usable tools for doing this stuff then we need
some basic conventions around how to represent things like links and
embedded resources. That's all HAL is.

The "craft" of building your API should be in designing the relations
and transitions between your resources (i.e. where interesting stuff
actually happens), and carefully exposing them to the outside world so
that it can be easily built against but with some degree of
malleability.

Using HAL means you don't have to spend time worrying about processing
rules, you should have a bunch of generic tooling for serving your
API, and likewise your clients have a range of existing tools for
consuming your API.

Is there really that much "noise" or "over-engineering" in HAL? As
with everything, there were trade-offs in each part of the design, but
reducing noise and keeping things simple was a key driver of the
original design.. e.g. everything it exposes is accessible via
standard JSON traversal:

root property:

response.foo

a link object:

response._links.bar

an embedded resource:

response._embedded.customer

If you have some specific thoughts on where HAL could be simplified
then definitely share them, but it's a bit hard to have a decent
conversation about your "feelings" on non-specifics like "noise" and
"over-engineered-ness".

Cheers,
M

[Mike Kelly]

On Fri, Jan 4, 2013 at 4:15 PM, mca <m...@amundsen.com> wrote:
> neither of which i offered up.
>
> but thanks.
>

you're welcome..! :)

seriously though, your actual examples didn't really make much sense..

e.g.:

myStuff.toURITemplate()

why is there no actual uri template supplied there? am I missing
something.. shouldn't it look something like this?:

myStuff.toURITemplate(template)

or even:

new URITemplate(template).expand(myStuff)

same deal with the form URL encoded example.

[mca]

well, maybe myStuff has a template property but you can add a template arg for that example if that makes it easier to answer my questions about your judgement regarding the relative "ease" and "complexity" of the various examples i provided (e.g. JSON, URITemplate, FormURLEncoded).

mca

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

[Mike Kelly]

On Fri, Jan 4, 2013 at 5:05 PM, mca <m...@amundsen.com> wrote:
> well, maybe myStuff has a template property but you can add a template arg
> for that example if that makes it easier to answer my questions about your
> judgement regarding the relative "ease" and "complexity" of the various
> examples i provided (e.g. JSON, URITemplate, FormURLEncoded).
>

Fair enough. These are obviously both loaded terms and highly
subjective, but here's how I would use them (and why):

JSON is easy and relatively non-complex (ubiquitous, simple media type)

URI Template is easy and relatively complex (good no. of libs, fairly
complicated processing rules)

FormURLEncoded is easy and relatively non-complex (assume good no. of
libs?, fairly simple processing rules?)

Form generated bodies are non-easy and complex (hardly any libs,
fairly complicated processing rules)


hope that helps?

Cheers,
M

[mca]

well, what i was asking you about was the function signatures.  IMO, none of them are more "complex" than the other and all as just as "easy" for a dev to use. and all of them are, from my POV, valid sigs to expect libs to provide.

based on you responses below, i think you are passing judgement on the level of complexity _behind_ the signatures i offered. interesting, for sure. but, again, not what i was asking about.

 

mca

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

M

[Mike Kelly]

On Fri, Jan 4, 2013 at 5:39 PM, mca <m...@amundsen.com> wrote:
> well, what i was asking you about was the function signatures. IMO, none of
> them are more "complex" than the other and all as just as "easy" for a dev
> to use. and all of them are, from my POV, valid sigs to expect libs to
> provide.
>
> based on you responses below, i think you are passing judgement on the level
> of complexity _behind_ the signatures i offered. interesting, for sure. but,
> again, not what i was asking about.

ok cool, sorry for the confusion was not intentional

[Glenn Block]

So back to the self link question.....

#ducks

[Mike Kelly]

On Fri, Jan 4, 2013 at 5:48 PM, Glenn Block <glenn...@gmail.com> wrote:
> So back to the self link question.....
>
> #ducks
>

Yes, good idea! :)

I can see arguments on both sides, seems like it's basically down to
personal preference. Personally I prefer always including a self link
(in some fashion) so that a representation is consistent whether the
it is contained in another resource or the actual target of the
request. But I can totally see why the redundancy that causes against
HTTP might bother people. Neither approach is "wrong".

[Glenn Block]

I agree. I also prefer to have it for consistency and I think the cost is negligible, buy yes. 

[Eric Elliott]

- Client parsing libraries can deal purely in terms of JSON and do not
need access to some data structure representing the response/request.

- The way you represent a resource is consistent whether embedded or
not, and this is good because it's a simpler model and makes stuff
like server-side or edge-side includes possible. 

 

 

there are probably other reasons they're just not coming to mind right now

* Embedded resources (as you already mentioned)

* Canonical URL representation (there's also rel: canonical, but I think that's redundant with rel: self, and likely to be less popular in hypermedia APIs)

- ee

[Jørn Wildt]

I just saw another use for "self" links at the root level even if the actual URL is the same as the URL used to fetch the resource: if the resource has different media type representations then a collection of "self" links can announce other possible representations if each of the self link definitions contains the possible media type declaration.

/Jørn

[Jack Snow]

Wow! A lot of very useful replies!

 

I have read a bit more about things like JSON HAL etc and can see that there is some benefit to providing links. In particular, the client would not need to implement code to generate links and the logic can live on the server.

 

Having said that, I have not really seen any of the major APIs (Facebook, twitter, flickr) return a standard format with metadata at all. They also don't seem to return any "self" links. Any comments on this?

[Glenn Block]

Some don't and some do, i.e. the github APi that I mentioned. I think traditionally many API authors have not been paying attention to linking. Part of that I think has to do with timing. The community has been doing a lot of working understanding what hypermedia is about, formats like collection+json and HAL emerging. This is helping to drive more though in this manner. Github I think is an example of an API that has embraced this.

Just because many other APIs have not done it, doesn't mean there is not value. For example Kelly Sommers (@kellabyte) has a nice blog post[1] on REST where she talks specifically about the twitter API and how it could have used linking but didn't.

1-http://kellabyte.com/2011/09/04/clarifying-rest/

--

[Kurt Kanaskie]

Great thread, I'm deep into our API Design guidelines and was reluctant to take on Hypermedia APIs (HAPIs - cant believe no one suggested this acronym yet) but after reading this thread and HAL spec, it doesnt look that daunting any more, thanks.

Tracking various best practices and webinars, I'm settling in on this design, before HAL:

{

  "orders": {

    "meta": { ... },

    "order": [

      { ... },

      { ... }

    ]

  }

}

One of my goals is to support bi-directional XML to JSON translation, so I need the outer "orders" element, otherwise the generated XML doesnt have a root element. I'm also thinking of using this format even for a single resource get, just to be consistent (its the engineer in me).

After HAL:

{

  "orders": {

    "meta": { ... },

    "_links": { ... },

    "_embedded": {

        "order": [

          { ... },

          { ... }

        ]

     }

  }

}

Seems pretty straight forward, I like the structured, consistent approach, perhaps maybe "_meta" for additional consistency?

So my question is, does JSON with an outer wrapper cause developers heartburn?

Thanks, Kurt

[Kevin Swiber]

On Jan 11, 2013, at 11:54 AM, Kurt Kanaskie <kurt.k...@gmail.com> wrote:

> So my question is, does JSON with an outer wrapper cause developers heartburn?

Yes, but heartburn isn't that bad. If I have to, I can tolerate it. ;)

If you're doing this for XML transformation benefits, maybe there's some info you can add to your meta object.

{
"meta": { "collection": "orders" },
"_embedded": []
}

As an API consumer, I'd be okay with that.

Regards,

Kevin

[Mike Kelly]

On Fri, Jan 11, 2013 at 4:54 PM, Kurt Kanaskie <kurt.k...@gmail.com> wrote:
> Great thread, I'm deep into our API Design guidelines and was reluctant to
> take on Hypermedia APIs (HAPIs - cant believe no one suggested this acronym
> yet) but after reading this thread and HAL spec, it doesnt look that
> daunting any more, thanks.
>
> Tracking various best practices and webinars, I'm settling in on this
> design, before HAL:
> {
> "orders": {
> "meta": { ... },
> "order": [
> { ... },
> { ... }
> ]
> }
> }
>
> One of my goals is to support bi-directional XML to JSON translation, so I
> need the outer "orders" element, otherwise the generated XML doesnt have a
> root element.

Hi Kurt,

Why do your json and xml representations need to be tied together link
this? Is it a limitation of the development stack you are working
with?

Cheers,
M