how to handle deep linking

[Peter Whitfield]

I wasn't able to find any discussion of this previously, so  my apologies if I'm re-asking an old question.

I'm dealing with an implementation debate about hypermedia APIs relating to deep linking and bookmarks. The question centres around how to handle situations where a client application has multiple entry points, in particular if one wants to navigate straight to a resource which would otherwise require following a number of links from the root API entry point.

Related to this question is the debate about how you allow third parties to save deep links direct to a specific resource without compromising the encapsulated nature of the API.

I hope my question makes sense - I've been trying to find any generally accepted solution to this problem by haven't found anything conclusive. One of our devs was suggesting that we use URI Templates and return a template for every resource available through the API in the root API request - this doesn't sound like a good idea to me but would appreciate oterh opinions.

Thanks,

Pete

[Irakli Nadareishvili]

Pete,

that is a common and a very fair question. Fortunately, it is also a problem that has a known solution. 

Proper Hypermedia API client should implement caching, and be pretty aggressive about it. There's no need to traverse entire path to a far-away resource every time you need the resource. It's worth to note that, as with all caching on the web, the client TTL of the cache must be informed by the cache instructions sent by the server (the API)—either through max-age or ETag headers.

Hope this helps.

Irakli

[Ruben Verborgh]

Hi Peter,

> The question centres around how to handle situations where a client application has multiple entry points, in particular if one wants to navigate straight to a resource which would otherwise require following a number of links from the root API entry point.

There is actually no such thing as an entry point of an API.
Sure, there is the one resource in your mind as an API designer that you consider "home";
however, that does not mean that this is the point through which clients will enter.
That's the whole point of the Web… any resource can link to any other resource,
and those resources do not have to be limited to a single API.

For instance, suppose my "nice places" application
wants to link to your "find flights" application.
If the user is currently browsing “London",
I'm not going to tell him or her:
“Well, here's the home page… and follow links X and Y, and click Z, and you'll be there”.
No, I will link to your resource that has flights for London
(probably after having followed the links in your application myself).

This kind of passing the navigation path was common before the Web [1],
but should not be a practice nowadays.

Also, designing an API with a fixed navigation path in mind
lead to problems such as this one [2].

> Related to this question is the debate about how you allow third parties to save deep links direct to a specific resource without compromising the encapsulated nature of the API.

Well, you design your URI space in a way that allows to keep them constant.
The navigation still happens through hypermedia (and always will),
but the way you allocate URIs ensures you can maintain them in the long run [3].

Concluding, don't talk about “deep links“. In a hypermedia world, that concept doesn't exist.
A link is a link, whether it happens to go to / or /flights/places/london.

Best,

Ruben

[1] http://ruben.verborgh.org/phd/hypermedia/#flyer
[2] https://gist.github.com/RubenVerborgh/7684361#comment-959892
[3] http://www.w3.org/Provider/Style/URI.html

[Irakli N.]

Ruben,

I respectfully disagree. During any interaction with a Hypermedia API, you can certainly start your interaction at any URI, but the notion of “home” in a Hypermedia API isn’t superficial. 

This:

> Well, you design your URI space in a way that allows to keep them constant. 

is a Linked Data view of the world and probably the biggest difference between Hypermedia and Linked Data's world perspectives. Linked Data folks want URIs to be forever, because that really helps the addressability. Hypermedia “philosophy” doesn't consider URIs to be forever. That just isn’t practical and what happens in real life.

As a matter of fact, considering URIs to be forever would be against the spirit of dynamic communication of affordances. If URIs are forever, then it follows that you can actually “hardcode” (Note: not cache for a long time, but actually hardcode) them in the client. At that rate you may as well write HTTP CRUD APIs.

The big win of Hypermedia APIs over HTTP APIs is removal of coupling between an API client and API server. Assuming “URIs are forever” cements that coupling.

In Hypermedia the media type is the constant, not the URI.

Backwards- and forwards- compatibility in Hypermedia doesn’t extend to actual URIs. Thinks of the World Wide Web: do most of the URIs that existed 5 years ago, still function and return the same entities? Of course not! Can browsers still process HTML4 or even HTML3 if the server responds with those? Yes!

Same goes for Hypermedia APIs.

Irakli

From: Ruben Verborgh ruben.v...@ugent.be
Reply: hyperme...@googlegroups.com hyperme...@googlegroups.com
Date: March 14, 2014 at 7:00:09 AM
To: hyperme...@googlegroups.com hyperme...@googlegroups.com
Subject:  Re: how to handle deep linking

Hi Peter,

> The question centres around how to handle situations where a client application has multiple entry points, in particular if one wants to navigate straight to a resource which would otherwise require following a number of links from the root API entry point.

There is actually no such thing as an entry point of an API.
Sure, there is the one resource in your mind as an API designer that you consider "home";
however, that does not mean that this is the point through which clients will enter.

That's the whole point of the Web... any resource can link to any other resource,

and those resources do not have to be limited to a single API.

For instance, suppose my "nice places" application
wants to link to your "find flights" application.
If the user is currently browsing "London",
I'm not going to tell him or her:

"Well, here's the home page... and follow links X and Y, and click Z, and you'll be there".

No, I will link to your resource that has flights for London
(probably after having followed the links in your application myself).

This kind of passing the navigation path was common before the Web [1],
but should not be a practice nowadays.

Also, designing an API with a fixed navigation path in mind
lead to problems such as this one [2].

> Related to this question is the debate about how you allow third parties to save deep links direct to a specific resource without compromising the encapsulated nature of the API.

Well, you design your URI space in a way that allows to keep them constant.
The navigation still happens through hypermedia (and always will),
but the way you allocate URIs ensures you can maintain them in the long run [3].

Concluding, don't talk about "deep links". In a hypermedia world, that concept doesn't exist.
A link is a link, whether it happens to go to / or /flights/places/london.

Best,

Ruben

[1] http://ruben.verborgh.org/phd/hypermedia/#flyer
[2] https://gist.github.com/RubenVerborgh/7684361#comment-959892
[3] http://www.w3.org/Provider/Style/URI.html

--
You received this message because you are subscribed to a topic in the Google Groups "Hypermedia Web" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/hypermedia-web/fWjqit3KtZQ/unsubscribe.
To unsubscribe from this group and all its topics, send an email to hypermedia-we...@googlegroups.com.
To post to this group, send email to hyperme...@googlegroups.com.
Visit this group at http://groups.google.com/group/hypermedia-web.
For more options, visit https://groups.google.com/d/optout.

[Ruben Verborgh]

Hi Irakli,

> but the notion of “home” in a Hypermedia API isn’t superficial.

Why wouldn't it be?
Sure, we have the / resource, and everything should be reachable from there in the end.

But from any other resource, the / resource should also be reachable; and thus in turn, any other resource.
However, the / resource is not necessarily the only way to get from a resource to another.

So in that sense, the home resource might as well be /flights/london/paris/,
because I can reach any other resource from it as well.

And should the /flights/london/paris/ cease to exist,
just serve me a nice 404 with links and I'll figure out where it is myself,
without ever needing any home resource.

That is hypermedia. I have one resource, I can get to another.
I don't need a special home resource to do that.

> is a Linked Data view of the world and probably the biggest difference between Hypermedia and Linked Data's world perspectives.

Linked Data is just saying to Data people: offer your data as a hypermedia API.

Observe that the Linked Data principles are just the REST architectural constraints (which include hypermedia)
but rephrased as principles. This becomes apparent if we reshape the REST constraints as principles too:
http://ruben.verborgh.org/phd/semantics/#the-rest-principles

> Linked Data folks want URIs to be forever, because that really helps the addressability.

Why would anybody ever want anything else?

How could I link from a resource in my hypermedia API to a resource in yours
if you keep changing its URI?

> Hypermedia “philosophy” doesn't consider URIs to be forever.

For a single API, this might work. Just use HATEAOS indeed.

But if you consider the Web as the API?
If you want APIs that cross borders and link to each other?
Oh yes, we want resources to maintain their URIs.

The Web can scale because links can break;
if we make sure our own links don't break,
people can build reliable applications on top of our things.

> As a matter of fact, considering URIs to be forever would be against the spirit of dynamic communication of affordances. If URIs are forever, then it follows that you can actually “hardcode” (Note: not cache for a long time, but actually hardcode) them in the client. At that rate you may as well write HTTP CRUD APIs.

No. The fallacy in this reasoning is that you can hardcode anything with persistent URIs.
You can't, and that is exactly why we have hypermedia.

In particular, you cannot hardcode URIs to resources that do not exist yet.
But you can say: well, here's the resource with "latest news about London”,
and tomorrow, the user will be able to follow links to tomorrow's articles.
You cannot give those links yourself, because they don't exist yet today.

What you may not hardcode is a URI pattern.
For instance, just because the first article in today's news is located at
/news/london/2014/03/14/articles/1
doesn't give you the right to assume that tomorrow's first article will be located at
/news/london/2014/03/15/articles/1
That is invalid.

What you can do is say:
/news/london
because this resource exists today and has a link to the latest articles.
Tomorrow, that link might be any of those:
- /news/london/2014/03/15/articles/1
- /news/london/2014-03-15/articles/1
- /news/london/the-queen-has-a-new-hat
- /dgsgyitYGhlhghkl4646
- …
No matter what it is, you will be able to follow it through /news/london,
because a) that resource's identifier and b) its media type are constant.
Hypermedia.

And no matter what the URIs of tomorrows' articles look like,
that doesn't create a need to change the URIs of todays'.
Hypermedia too, because I just linked to today's article
and you break my API if you change your URIs.

We have to stop thinking about APIs as silos.

> The big win of Hypermedia APIs over HTTP APIs is removal of coupling between an API client and API server.

Yes.

> Assuming “URIs are forever” cements that coupling.

No.

In fact, it removes the ability for a resource in one API to link to a resource in another.
You as a server gave me an identifier. I didn't decide it. No coupling there.

> Backwards- and forwards- compatibility in Hypermedia doesn’t extend to actual URIs.

Why not? Give me a good reason not to keep your existing URIs.

And even if you decide to break existing URIs,
let me bookmark /news/london.
Just make sure that the 404 for /news/london
allows me to navigate through hypermedia to where I want to go.
(But better, keep it. Or make it a 301.)

> Thinks of the World Wide Web: do most of the URIs that existed 5 years ago, still function and return the same entities?

Well, they better give a 404 if they don't.
If /news/london suddenly points to the news for Paris, that's a major problem.
You can break URIs, sure… but give me 404/410 and never put a different resource at the same place.

I wish that Tim Berners-Lee's response while discussing
http://www.w3.org/2012/ldp/track/issues/24 would have been recorded on video;
it was a very passionate

“Never… ever ever… in the entire history of the… universe… [*raises arms above head*]
should a URL allowed to be reused for a different thing.”

> Of course not! Can browsers still process HTML4 or even HTML3 if the server responds with those? Yes!

Well, I don't mind if my /news/london resource in the future gives me the latest news for London in HTML7.
As long as it is still the same resource… or an error resource that allows me to locate that news.

Best,

Ruben

[Irakli N.]

Ruben,

I am completely, 100% with you on “URIs shouldn’t be re-used”. But that’s not the issue at hand here. Furthermore: I wouldn’t mind at all if URIs were forever, it just isn’t practical. REST and Hypermedia are like Physics: they describe the realities of the nature, we can’t just invent the reality we want. The [sad] reality is that URIs get broken all the time. Even if they don’t get re-used broken start URL kills your API client right there.

In reality the difference between “URL doesn’t exist anymore” 404 and “never existed” 404 is not there. “Old URLs” 404-ing do not give you information about what to do in the new world. If they did, they’d be 3xx responses.

If your API client always starts its navigation at /news/london/2014/03/15/articles/1 and that URL suddenly 404s—chances are you have no idea what to do. At that point your only sensible “fallback” is to go back and check the Home of the API—and that is exactly why Home document of APIs are special.

It’s a social contract. I know most of the time all of website’s bookmarked URLs work, but if they break, the only thing I can rely on is that the root URL will still be there, helping me figure out what to do. Same is true for APIs.

Bottom-line:

if you are saying “cache a ‘deep resources’ URL until it 404s’, but don’t hardcode it” then we are in agreement (despite our remaining differences on Linked Data view of URIs :))). Purely in the context of where to enter an API, such strategy would work. For other caching considerations, I’d rather API tell me how long to cache each endpoint, but purely for the sake of navigation—“until 404” caching sounds reasonable.

Irakli

From: Ruben Verborgh ruben.v...@ugent.be
Reply: Ruben Verborgh ruben.v...@ugent.be
Date: March 14, 2014 at 10:35:43 AM
To: Irakli N. ira...@gmail.com
Cc: hyperme...@googlegroups.com hyperme...@googlegroups.com
Subject:  Re: how to handle deep linking

[Ruben Verborgh]

Hi Irakli,

> I wouldn’t mind at all if URIs were forever, it just isn’t practical.

Why not? Millions of telephone numbers have been constant for decades;
so have millions of e-mail addresses.
And it's actually easier to keep URIs constant if you control the domain name.

> REST and Hypermedia are like Physics: they describe the realities of the nature, we can’t just invent the reality we want.

They're not. Physics describes the reality we happen to live in.
Web APIs we build ourselves. We're in control. We can design in a future-compatible way.

> The [sad] reality is that URIs get broken all the time.

Just because many APIs didn't do it in the past, doesn't mean we shouldn't do it now.

> In reality the difference between “URL doesn’t exist anymore” 404 and “never existed” 404 is not there.

Sure (410 aside), and that's not a necessity to help me find my way.

> “Old URLs” 404-ing do not give you information about what to do in the new world. If they did, they’d be 3xx responses.

No. It could be that the server has no clue what my old URL /news/london points to.
But at least it can say: "look men, these are interesting resources I have right now”.

If it has a clue what /news/london points to, then it's a 301.
And then it didn't break the URL. Hurray!

> If your API client always starts its navigation at /news/london/2014/03/15/articles/1 and that URL suddenly 404s—chances are you have no idea what to do.

Yep. That's why the 404 should tell me.

> At that point your only sensible “fallback” is to go back and check the Home of the API

No need for a home, just follow links in the 404.

> It’s a social contract. I know most of the time all of website’s bookmarked URLs work, but if they break, the only thing I can rely on is that the root URL will still be there

Helpful 404s are a lot better. On my site, you never have to change a URL to get to any resource:
http://ruben.verborgh.org/news/london

You don't have to know my home URL. Any URL of any resource that (n)ever existed on my API,
affords to access any other resource on my API.

> if you are saying “cache a ‘deep resources’ URL until it 404s’, but don’t hardcode it” then we are in agreement (despite our remaining differences on Linked Data view of URIs :)))

Sadly, no agreement ;-) [really joking here, I like the interesting discussion]

I say that, once a server has given you a URI, you can use it for eternity.
In the best case, it leads to the same resource.
In a slightly worse case, it redirects me to the same resource.
In the worst case*, it gives me an error page that allows me to reach any resource.

But never ever at any point do I need the URI of another resource to enter the API.

Best,

Ruben

* In the absolutely worst case, the server is dead and I'm on my own. But such are the consequences of eternity.

[Kevin Swiber]

On Fri, Mar 14, 2014 at 11:16 AM, Ruben Verborgh <ruben.v...@ugent.be> wrote:

Hi Irakli,

> I wouldn't mind at all if URIs were forever, it just isn't practical.

Why not? Millions of telephone numbers have been constant for decades;
so have millions of e-mail addresses.
And it's actually easier to keep URIs constant if you control the domain name.

> REST and Hypermedia are like Physics: they describe the realities of the nature, we can't just invent the reality we want.

They're not. Physics describes the reality we happen to live in.
Web APIs we build ourselves. We're in control. We can design in a future-compatible way.

> The [sad] reality is that URIs get broken all the time.

Just because many APIs didn't do it in the past, doesn't mean we shouldn't do it now.

> In reality the difference between "URL doesn't exist anymore" 404 and "never existed" 404 is not there.

Sure (410 aside), and that's not a necessity to help me find my way.

> "Old URLs" 404-ing do not give you information about what to do in the new world. If they did, they'd be 3xx responses.

No. It could be that the server has no clue what my old URL /news/london points to.
But at least it can say: "look men, these are interesting resources I have right now".

If it has a clue what /news/london points to, then it's a 301.
And then it didn't break the URL. Hurray!

> If your API client always starts its navigation at /news/london/2014/03/15/articles/1 and that URL suddenly 404s--chances are you have no idea what to do.

Yep. That's why the 404 should tell me.

> At that point your only sensible "fallback" is to go back and check the Home of the API

No need for a home, just follow links in the 404.

> It's a social contract. I know most of the time all of website's bookmarked URLs work, but if they break, the only thing I can rely on is that the root URL will still be there

Helpful 404s are a lot better. On my site, you never have to change a URL to get to any resource:
http://ruben.verborgh.org/news/london

You don't have to know my home URL. Any URL of any resource that (n)ever existed on my API,
affords to access any other resource on my API.

> if you are saying "cache a 'deep resources' URL until it 404s', but don't hardcode it" then we are in agreement (despite our remaining differences on Linked Data view of URIs :)))

Sadly, no agreement ;-)    [really joking here, I like the interesting discussion]

I say that, once a server has given you a URI, you can use it for eternity.
In the best case, it leads to the same resource.
In a slightly worse case, it redirects me to the same resource.
In the worst case*, it gives me an error page that allows me to reach any resource.

But never ever at any point do I need the URI of another resource to enter the API.

Some other benefits to decoupling clients from the URL structure of an API:

1. In globally distributed scenarios, clients can be served URLs to their closest data center.  This obviates the need for GeoDNS tricks.

2. Clients can be built with knowledge of multiple root URLs to try should an endpoint become unavailable.  This is a distributed computing technique that works well to avoid the perils associated with single points of failure.

Do you need a requirement of independent evolution between client and server implementations?  If so, how deep does that requirement go?  How does that impact the contract between client and server?  These are the questions to ask.

Whether the intention is to keep a URL permanent or not, we all dial the wrong number sometimes.  In some cases, Not Found responses may provide an affordance for course correction.

--
Kevin Swiber

Projects: https://github.com/kevinswiber
Twitter: @kevinswiber

[Mike Schinkel]

On Mar 14, 2014, at 11:16 AM, Ruben Verborgh <ruben.v...@ugent.be> wrote:
> Hi Irakli,
>
>> I wouldn't mind at all if URIs were forever, it just isn't practical.
>
> Why not?

Because not all URIs are "Cool." ;)

-Mike

[Joe Kowalski]

> Why not? Millions of telephone numbers have been constant for decades; so
have millions of e-mail addresses.

But the context of the resource here is not constant, it's fluid. This means
the content type is not constant. So now when the credit company calls the
number I now own looking for "Jimmy" and I tell them I'm not "Jimmy" they
get an unexpected result. And me telling them does nothing to update the
global understanding of that resource identifier (phone number).

Now; if they knew where they could find "Jimmy" and the service was HATEOAS
friendly, they would know his real fricken' phone number.

:-)

~Joe

-----Original Message-----
From: hyperme...@googlegroups.com
[mailto:hyperme...@googlegroups.com] On Behalf Of Mike Schinkel
Sent: Friday, March 14, 2014 10:44 AM
To: hyperme...@googlegroups.com
Subject: Re: how to handle deep linking

--
You received this message because you are subscribed to the Google Groups
"Hypermedia Web" group.
To unsubscribe from this group and stop receiving emails from it, send an

[Ruben Verborgh]

> Some other benefits to decoupling clients from the URL structure of an API:

The issue is not about decoupling; like I said, the server determines the URL.
Instead, the question is about whether this URL remains constant during its lifetime.

> In some cases, Not Found responses may provide an affordance for course correction.

They should in all cases. No reason not to do it.

Best,

Ruben

[Martynas Jusevičius]

Irakli,

besides URIs, another important aspect of Linked Data is RDF, which
Ruben failed to mention. In RDF, URIs are built into the data model.
If you build semantic applications using triplestore, you have a
database full of URIs. The HTTP API (Linked Data) simply reflects the
state of your RDF data. If your data is forever, then your URIs are
forever too.

This is actually a very generic and straightforward software design
pattern, but you have to try it to understand it. Good luck with
Hypermedia though.


Martynas
graphityhq.com

> You received this message because you are subscribed to the Google Groups
> "Hypermedia Web" group.
> To unsubscribe from this group and stop receiving emails from it, send an

[Mike Kelly]

On Sat, Mar 15, 2014 at 12:05 AM, Ruben Verborgh <ruben.v...@ugent.be> wrote:

> Some other benefits to decoupling clients from the URL structure of an API:

The issue is not about decoupling; like I said, the server determines the URL.
Instead, the question is about whether this URL remains constant during its lifetime.

Are you sure? Why should it remain constant?

[Mike Kelly]

On Sat, Mar 15, 2014 at 12:35 AM, Martynas Jusevičius <mart...@graphity.org> wrote:

Irakli,

besides URIs, another important aspect of Linked Data is RDF, which
Ruben failed to mention. In RDF, URIs are built into the data model.
If you build semantic applications using triplestore, you have a
database full of URIs. The HTTP API (Linked Data) simply reflects the
state of your RDF data. If your data is forever, then your URIs are
forever too.

This is actually a very generic and straightforward software design
pattern, but you have to try it to understand it. Good luck with
Hypermedia though.

I definitely would not describe real world RDF as "straightforward".

I imagine there are many who agree which is probably why it still has relatively low adoption, even after an epic 15+ year slog.

Also, I really hope nobody brings up Range-14.

... ;)

Cheers,

M

[Martynas Jusevičius]

Sorry Mike, paradigm shifts are always hard :)

[Mike Kelly]

indeed.

So is admitting when you've got it wrong - it's so hard to tell, sometimes..! ;)

--
Mike

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

[Kevin Swiber]

On Fri, Mar 14, 2014 at 8:05 PM, Ruben Verborgh <ruben.v...@ugent.be> wrote:

> Some other benefits to decoupling clients from the URL structure of an API:

The issue is not about decoupling; like I said, the server determines the URL.
Instead, the question is about whether this URL remains constant during its lifetime.

However you wish to restate the problem, the model you're proposing misses the benefits listed.  That's something to consider.  To provide context for posterity, I'll re-list those points here:

1. In globally distributed scenarios, clients can be served URLs to their closest data center.  This obviates the need for GeoDNS tricks.

2. Clients can be built with knowledge of multiple root URLs to try should an endpoint become unavailable.  This is a distributed computing technique that works well to avoid the perils associated with single points of failure.

 

> In some cases, Not Found responses may provide an affordance for course correction.

They should in all cases. No reason not to do it.

I avoid presumptions about the entire body of use cases mankind can muster. 

[Ruben Verborgh]

> besides URIs, another important aspect of Linked Data is RDF, which
> Ruben failed to mention.

Failed to mention? Since when was this a discussion about Linked Data?
And even if it were, constant, dereferencable URLs are part of Linked Data, not RDF.

> The HTTP API (Linked Data) simply reflects the
> state of your RDF data.

It does not. RDF uses IRIs as identifiers.
Linked Data says to use URLs, so you can look up more.
In no case does HTTP reflect state of your data.
RDF keeps working even if URLs break; Linked Data does not.

But let's keep this discussion on track:
the necessity of persistent URLs and special entry points for hypermedia.

Best,

Ruben

[Ruben Verborgh]

>> The issue is not about decoupling; like I said, the server determines the URL.
>> Instead, the question is about whether this URL remains constant during its lifetime.
>
> Are you sure? Why should it remain constant?

My arguments for keeping them constant:

- https://groups.google.com/forum/#!msg/hypermedia-web/fWjqit3KtZQ/hBvHpmSgqNwJ
- https://groups.google.com/forum/#!msg/hypermedia-web/fWjqit3KtZQ/_o8PvrMRs00J
- https://groups.google.com/forum/#!msg/hypermedia-web/fWjqit3KtZQ/nMAM2ecZFJoJ

And note how meta this is… :-)
If the above URLs don't remain constant,
this message by itself will be meaningless in some time.
Better hope they serve a good 404 resource then.

Cheers,

Ruben

[Ruben Verborgh]

Hi Kevin,

>> The issue is not about decoupling; like I said, the server determines the URL.
>> Instead, the question is about whether this URL remains constant during its lifetime.
>
> However you wish to restate the problem, the model you're proposing misses the benefits listed.

No.

> 1. In globally distributed scenarios, clients can be served URLs to their closest data center.

What I said does not affect that:
“like I said, the server determines the URL.“

So clients can still be served URLs to their closest data center.
“Instead, the question is about whether this URL remains constant during its lifetime.”

> 2. Clients can be built with knowledge of multiple root URLs to try should an endpoint become unavailable.

Then we're talking about multiple URIs on different servers.
They don't have to be “root“ URLs.

>> They should in all cases. No reason not to do it.
>
> I avoid presumptions about the entire body of use cases mankind can muster.

Exactly the reason hypermedia responses should include links to many resources,
not just the one resource of the use case you have in mind.

Cheers,

Ruben

[Glenn Block]

Hmm

The essence of hypermedia is removing the coupling of clients to the construction of URIs. The client makes an initial request (which it does construct the URI for) after which the server feeds it whatever it needs from that point on to transition to different states, whether that be links with absolute URIs / templates or forms.

Having bookmarks doesn't violate this. Clients can still remain decoupled as loon as that bookmark is opaque. The problems occur when the client reverse engineers those bookmarks and starts constructing new URIs based on making assumptions about the URI structure.

But that doesn't make a bookmark in it's essence problematic, it makes clients reverse engineering the URI space problematic.

What is the actual concern here? 

--
You received this message because you are subscribed to the Google Groups "Hypermedia Web" group.
To unsubscribe from this group and stop receiving emails from it, send an email to hypermedia-we...@googlegroups.com.

[Kijana Woodard]

Reading this thread with interest.

In order to be useful, the URIs in a response must have a lifetime greater than zero. Now we're just arguing the range between one and infinity.

Once you introduce 301, 404, 410 into the picture with the root uri as an escape hatch, it seems pretty well sewn up.

A client cannot construct URIs. Once obtained, they can be used until the server says stop.

Fair enough?

[Glenn Block]

That makes sense to me.

[Joe Kowalski]

Ding

~Joe

Sent from my Windows Phone

---

From: Glenn Block
Sent: ‎3/‎14/‎2014 7:56 PM
To: hyperme...@googlegroups.com
Cc: Kevin Swiber

Subject: Re: how to handle deep linking

[Ruben Verborgh]

> Once you introduce 301, 404, 410 into the picture with the root uri as an escape hatch, it seems pretty well sewn up.

+1, except the “root URI” concept is still pretty unnecessary.

Why would the “root URI” be more constant than any other?
Unless it is just /, but you can always try that one.
And if there were a “root URI”, how will you universally recognize it in any representation?
And does that mean you will always have to store it with any URI you bookmark?

Let's just design our APIs so all resources (error or not) allow to reach all others,
i.e., making the hypermedia graph connected. And maximize a URL's lifetime.
And if you feel you have to break a URL, never reuse it for something else.

> In order to be useful, the URIs in a response must have a lifetime greater than zero. Now we're just arguing the range between one and infinity.

> A client cannot construct URIs. Once obtained, they can be used until the server says stop.

Absolutely. Good summary.

Cheers,

Ruben

[Kijana Woodard]

Gotcha.

Could include a "home" rel in every response in addition to other meaningful links. I think this gives some interesting affordances.

Also seems likes this model gives greater weight to a profile or self rel to be explicit about the media type in the response rather than relying on the rel that was accessed.

[Peter Whitfield]

Wow, you go offline for a weekend and miss the whole discussion!

Thanks everyone for your contributions, I've learnt quite a bit from reading through the thread.

to provide some context for my original question, I was working on the assumption that a core principle of hypermedia APIs was that an API client should be able to rely on a published 'entry point' URI such as '/' and that it shouldn't make any further assumptions about resource URIs from that point on. Obviously you can have more than one 'known' URI, but the more you have, the more tightly coupled the client and server are.

If you think of the web as an example, I have no idea about what links exist within that website until I load the home page. Of course I can start guessing URIs and look at the responses to work out where to go from there, but I think having the 'entry point' of a homepage is a normal situation.

If I consider a client which isn't caching previously accessed resource URIs, then it must be either constructing URIs, or have some sort of 'entry point' to begin navigating the resource linkages.

I now understand better the 'deep linking' question - I should strive to maintain the provided URI for a resource that someone may want to reference directly and provide 3xx/4xx responses if I have to change it.

I was also under the impression that one of the benefits of the HATEOAS approach was that it helped me to address API versioning by allowing me to change the URI scheme in my API without worrying about clients that rely on out of band knowledge of the URI structure. So the discussion about not reusing a URI for a different resource isn't really relevant - I'm thinking more of the case where a new URI is defined for an existing resource.

I may post a more concrete example after I've discussed with the team.

Thanks!

Pete

.

[mca]

Peter:

The following is similar to the kind of text I encourage HTTP API providers to use as guidance (both internally and externally)

API Service Providers (Servers)

Service providers MUST provide at least one stable URL which client apps can use to access the service.  Providers MAY supply more than one stable URL for service access. All URLs supplied by the provider MUST be resolvable and providers are responsible for gracefully deprecating any published URLs via 3xx redirects or informative 410 Gone responses (See RFC2616).

API Service Consumers (Clients)

Service consumers SHOULD use the stable URL(s) supplied by the service provider when accessing the service. Consumers MAY cache (bookmark) subsequent URLs and use them as access points. While consumers are free to attempt to construct URLs in order to gain access to the service, consumers MUST be prepared for providers to return 3xx or 4xx responses on all URLs; especially those not published by the provider.

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

.