HATEOAS - Full URLs or Fragment

[Jack Snow]

Google groups is strange these days. If I post a message with a link,
it gets deleted immediately!

Anyway, here's my second try:

HATEOAS is very nice in that it allows us to provide links to the
client so they don't have to generate the links themselves.

Here's an example using JSON HAL:

{ "_links": { "self": { "href": "http://example.com/" } } }

The question is, do I provide a full link: http://api.site.com/v1/some/resource
or a fragment: /some/resource?

Which is more correct?

[Steve Klabnik]

While it's not really a matter of 'correctness' as to relative / full
URLs, it's nice not to have to build the URL at all, so I generally
include the full URL.

[Terry McConnell]

What about in situations where you need to support multiple environments (e.g. SIT, UAT, or Development) which have different entry URLs?  ( api-sit.example.com vs. api.example.com)

[Steve Klabnik]

Then when I visit it via api-sit.example.com, it returns URLs with
that as the 'base', and when you visit it via api.example.com, it
returns URLs with that as the base.

Rails makes this trivial:

entry_url(@entry)

gives

http://localhost:3000/entries/1

in development, and

http://thisismyactualdomain.com/entries/1

in production, for example. I assume your environment has something
similar, and if it doesn't, it should!

[Glenn Block]

you can use relative urls, I use them sometimes when just prototype. I prefer absolute particularly if my links are inline because I can copy-paste the body and it has everything it needs. 

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

[Jørn Wildt]

Neither is more correct than the other - but your client developer adoption rate is probably going to be higher if you supply full URLs.

Why put the burden of URL construction on the client when the server has full knowledge of the URL anyway? You can probably find some exotic use cases for relative URLs - but in general I would say they are nothing but an extra burden for the client.

/Jørn

[Felipe Sere]

I cant even THINK of a reason for why relative URLs would make sense... 

--
Gruß,
Felipe

[Mike Kelly]

If you version and/or partition your environments via the domain name
then using only the resource path can work well. (i.e. /foo/bar)

It means that clients "bookmarking" a resource are less likely to be
coupled to a particular version of your API.

Cheers,
M

Mike

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

[Felipe Sere]

Isn't that only relevant if you mix production and non-production machines and link across them?

[Mike Kelly]

It's more about versioning, so if you have

http://v1.example.com/widgets/123
http://v2.example.com/widgets/123

but your clients are exposing resource paths, i.e:

{
_links: {
widget: { href: "/widgets/123" }
}
}

then if clients chose to bookmark the URL in the above representation,
then they're decoupled from the version. Of course they could resolve
the path to an absolute URL and then bookmark /that/ but it does
reduce the likelihood of that happening.

To be clear, I'm playing devils advocate a bit here since you said you
couldn't think of any reason. I think absolute URLs are a fine choice.
:)

Cheers,
M

[Felipe Sere]

Still. Would you mix versions or have your client construct the uri so that he uses a specific version?

We only version representations by versioning the vendor types...

--
Gruß,
Felipe

[Mike Kelly]

I would encourage clients to construct their URI from a bookmarked
path by applying that path to the relevant entry point of the
application. I usually keep any versioning out of entry points anyway,
so it would end up looking something like this:

bookmark = "/widgets/123"

entry_point = "http://api.example.com/"

resolve(bookmark, entry_point)
#=> "http://api.example.com/widgets/123"

This is just _an_ approach, it's not something I do all the time.
Using absolute URIs is definitely simpler, it just gives you a little
less flexibility in some cases.. particularly around this issue of
'bookmarking'.

Cheers,
M

[Daniel Roop]

I would call it absolute vs relative.  I think fragments are more like #anchor which is a different concept but probably an interesting conversation.

I agree that both absolute and relative are "correct". I tend to recommend clients I control to support both, but my services I recommend returning absolute.

I do encourage the use of relative URL spec for handling relative URLs.  I think this would usually make Mike suggestion not work unless you define some other rule to determine the base than the document you received the URL from(which I think is OK as long as it is in your apis docs).

I have found both approaches have their own problem.  Absolute URLs require extensive URL rewriting to make sure your api is returning links to the appropriate environment, and depending on your system this could get complicated.  Relative however requires additional Client processing which isn't always trivial if you follow the spec and may hurt adoption.

I have worked with one api that supplied relative links for its resources and absolute when linking to an external system.  This has the downside of only allowing one external environment to be used with this service.  That of course is a problem with absolute in general but is exaggerated when linking between systems.

Relative URL spec: http://www.ietf.org/rfc/rfc1808.txt

- Daniel

[Felipe S.]

I know its an old thread by it just came up again with my colleagues.

They are building an API and expect the client to 'bookmark' certain URIs. They really care about this 'bookmarked URI' as they intend to compare it between clients to figure out who 'owns' something. Now, I am a strong advocate of absolute URLs, as I believe it to be non the concern of the client.

Hence I think that there are two things 'broken' in this design: URI comparison, rather than content comparison. A URI is just a pointer to a thing. If I want to compare that 'thing', URIs are dangerous because two different URIs can point to the same thing. Plus, URI can change and become invalid. Clients should be able to handle that.

But just for the sake of discussion: Is there anyone out there that has an API that supports or even encourages bookmarking URIs?

What do you do with such URIs?  What were arguments for 'bookmarking' a URL rather than the content the URL points to?

Cheers!

Felipe

[Madhusudan Joshi]

While implementing HATEOAS I use full URI. If you provide relative URI then it requires a liitle effort form consumer to build the complete URI. The easier it is for consumer, the better and it also attracts more consumer.

So complete URI should be used.

[Glenn Block]

There's nothing wrong with bookmarking IMO. And I agree with you, if you want to support bookmarking then absolute URIs are better. Bookmarking still doesn't bind the server so the client has to be prepared to handle the possibility of a redirect or even a 404. For example I know of one very large API that uses a lot of transient resources representing point-in-time conversations. In that case if you bookmarked the URI it would only be a valid resource for the life of the conversation.

I generally prefer bookmarking any day over clients manually building up URIs. Using URI templates though is an interesting option which still alleviates the client from hardcoding against the URI space.

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.

[Felipe Sere]

Hi Glenn,

In my mind I was trying to tackle it differently:

bookmarking URLs is bad unless both the client and the server uphold these URLs to either be long-living or that that they both do their best to compensate (redirects, handle 404 etc…).

That can work, but can be solved much more elegantly.

Say that your clients want to ‘remember’ some resource and pick it back up. If there was some kind of marker (e.g. token) in the body that the client could then use to query for that resource, the effect would be the same.

As a server, I have to provide a token  that uniquely identifies this resource (a token could be anything!)  then a means for finding the resource for that token (e.g. a query operation in Cj).

Wouldn’t that be far more elegant? URLs can still change and whatnot, yet the resource is still findable. 

My solution doesn’t constrain the problem more than URL bookmarking (something is still stored and must remain stable over an extended period of time), yet URLs remain free to change :-)

Does that make sense? 

Cheers,

Felipe