Parse Link headers (rfc5988)

[jokull]

Web Linking RFC

GitHub uses these for pagination in their API for example. Potentially they make API’s more self describing and discoverable.

I’d like to invite the discussion of requests making an effort to consume these and expose them on Response.links as a dictionary or dict-like object.

A HTTP Link header looks like this:

Link: <http://example.com/TheBook/chapter2>; rel="previous";
     title="previous chapter"

It’d be cool to access the links like so

response.links.previous
>>> Link <http://example.com/TheBook/chapter2> title="previous chapter"

Maybe this belongs in a requests-hypermedia library.

References:

• Link header parsing gist

[jokull]

Taking it further:

Enable HTTP verb actions on links. Think: response.links.next.get()

Chained request/response! ☺️

More on Hypermedia API linking

[kennethreitz]

I've been thinking about something like this for a long time.

If the API was kept this simple, I think we could keep this directly in Requests.

[jokull]

response.links.next vs. response.rel.next

[jokull]

HAL is now an Internet-Draft. This is likely to become the hypermedia guideline for expressing connections between resources (what the Link header does) with many more features.

Also @mitsuhiko expressed his hate for embedding "new things" into headers. I think it might have something to do with cachability or intermediaries that mess with headers.

See more:

• Backbone.HAL
• frenetic

[steveklabnik]

One of the reasons people don't use Link headers is the lack of tooling, so I'd love to see this in Requests, for obvious reasons.

This is likely to become the hypermedia guideline for expressing connections between resources (what the Link header does)

HAL is described my mike as "HTML for machines," so I think this description is slightly off. That said, I don't see why it's relevant to this discussion, exactly, so I should just shut up. :)

[timClicks]

One thought..

response.links.attr

should return the URI, rather than the raw data. We already have means of accessing headers.

[jokull]

@steveklabnik I suppose Link headers aren't going anywhere just because of HAL.

One question you might be more familiar with .. is the rel attribute a namespace of sorts for links? So suppose you had two ;rel=profile headers should one of them be ignored? I'm asking because the implementation would be nice as an attribute accessor like so:

response.links.profile
>>> "/some/uri"

HTML pages can link to multiple stylesheets, as is common.

[steveklabnik]

@jokull this is quickly getting off topic, and this might be a great question for the hypermedia@librelist.com list, but quickly:

Not so much a namespace as like a tag. Think about a collection:

<ul class="collection">
  <li><a rel="item current" href="...">one</a>
  <li><a rel="item" href="...">two</a>
  <li><a rel="item" href="...">three</a>
</ul>

Each one is an item, so each one would get an item rel. http://www.iana.org/assignments/link-relations/link-relations.xml

You could easily have it return an array rather than a string.

Note that non-standard link relations are supposed to be URIs, so accessing it via a method (sorry, Rubyist here primarily) means that when I have

<a href="..." rel="http://mysite.com/rels/blog-post">Links are awesome</a>

you're not gonna be able to use this interface to get response.links.http://mysite.com/rels/blog-post.

[kennethreitz]

Requests doesn't want to be involved with anything in the response body. Only headers.

[steveklabnik]

Link Relations work on any link, link header or in the response body. The issue is the same: two Link headers with an item relation is 100% compliant.

[jokull]

@kennethreitz Good point about headers vs body. Are you looking for contributors or suggested implementations?

One more reference: the official Link Relations.

[mnot]

FWIW, parser here:
https://github.com/mnot/redbot/blob/master/redbot/headers/link.py

[kennethreitz]

This is happening now.

>>> r.links['previous']
{'url': 'http://blahblah', 'type': 'whatever'}

[rhyselsmore]

Oh it is so happening.

[jokull]

I guess it’s a MultiDict with get_list?

[sigmavirus24]

A happier man today, I could not be.

✨ 🍰 ✨

[rhyselsmore]

f3159ed handles basic functionality

[chadwhitacre]

Very handy, thank you. :-) ❤️