Multiple usage of link header `rel`

[jhermsmeier]

Multiple usage of link header `rel`

[leipert]

Mhm. I will actually just be using the API for link parsing, so not too much just suggestions on the setters and getters. We are using lodash, i will just iterate over the refs once they are parsed.

If I would have to design the API it would probably look like this:

• Parser

  var link = LinkHeader.parse(
    '<example.com>; rel="example"; title="Example Website", ' +
    '<example-01.com>; rel="example2"; title="This is another Example Website", ' +
    '<example-01.com>; rel="alternate"; title="Alternate Example Domain"'
  )

• get/rel like lodash.find. I would always return an array, so that the user has a more consistent API to work with:

  /* returns
  [
   { uri: 'example.com', rel: 'example', title: 'Example Website' },
   { uri: 'example-01.com', rel: 'example', title: 'This is another Example Website' }
  ] */
  link.get({rel: 'example'})
  //alternative shorthand with same result
  link.rel('example')
  
  /* returns
  [
   { uri: 'example-01.com', rel: 'alternate', title: 'Alternate Example Domain' },
   { uri: 'example-01.com', rel: 'example', title: 'This is another Example Website' }
  ] */
  link.get({uri: 'example-01.com'})
  
  /* returns
  [
   { uri: 'example-01.com', rel: 'alternate', title: 'Alternate Example Domain' }
  ] */
  link.get({rel: 'alternate'})

• has

  // returns true
  link.has({rel: 'example'})
  // returns true
  link.has({rel: 'example', uri: 'example-01.com'})
  // returns false
  link.has({rel: 'example-nope'})

• remove/add. Remove should be silent, if no matching relation exists. Adding should throw, if rel or uri is missing. Adding should maybe throw, if a relation/uri combo already exists, otherwise it should overwrite the existing entry, like you do at the moment

  // add new example
  link.add({rel: 'example', uri: 'http://new-example.page'})
  // this should throw an error
  link.add({rel: 'example'})
  // returns example relation where URI also matches
  link.remove({rel: 'example', uri: 'example-01.com'})
  // removes all example relations
  link.remove({rel: 'example'})
  // You should do this to edit:
  link.remove({rel: 'alternate', uri: 'example-01.com'})
  link.add({rel: 'alternate', uri: 'example-01.com', title: 'What a new funny title'})

  You could also think about making the add/remove api fluent:

  link.add({...})
      .remove({...})
      .remove({...})
      .add({...})

• toString - as-is

[leipert]

I could also help with this feature, if you'd like

[leipert]

Furthermore i found this statement in the RFC 5988, §4:

Relation types SHOULD NOT infer any additional semantics based upon
the presence or absence of another link relation type, or its own
cardinality of occurrence

which seems not to exclude the possibility of a relation defined more than one time.

PS: We could also discuss this in German, if you prefer it ;)

[jhermsmeier]

The statement in the README is concerned with only the value of the Link header (or link-value, as it's called in the RFC) – where "reference" is supposed to denote the URI the link points to:

<example.com>; rel="example"; title="Example Website"
^-----------^
URI reference

As stated in RFC 5988, Section 5.3: Relation Type

The relation type of a link is conveyed in the "rel" parameter's
value. The "rel" parameter MUST NOT appear more than once in a given
link-value; occurrences after the first MUST be ignored by parsers.

That doesn't mean you can't have multiple link headers with the same rel attribute, though.
You're just not "allowed" to do things like <uri>; rel="this"; rel="that".

So I was wondering if an API change to accommodate multiple link headers would make sense for 1.0.0

This module is only concerned with parsing the link-value of a header, not making sense of a list of HTTP headers, so if you want to parse multiple link headers, you can just iterate over them:

var links = headers.map( LinkHeader.parse )

Hope that clarifies your question.

[jhermsmeier]

There's a bug in there though, I just noticed... I implemented it wrong, and you're right – it doesn't handle multiple link-values within one link header correctly. I shall fix that shortly.

[leipert]

Ha, we were not talking about the same thing. What i wanted to do is:

var LinkHeader = require( 'http-link-header' )
// expected link.refs to be an array with 2 objects,
// but actually contains just the first :)
var link = LinkHeader.parse(
  '<example.com>; rel="example"; title="Example Website", ' +
  '<example-01.com>; rel="example"; title="Alternate Example Domain"'
)

Try it here :
https://runkit.com/58458f4c9c82ac0014124f5b/58458f4c9c82ac0014124f5c

[jhermsmeier]

Yeah, sorry – I only noticed after I read through the README again. Somehow I can't think straight today. Thanks for bringing this up! I'll mark it as a bug, and started on fixing that, but it also made me think that I haven't set up the API that great for what it's supposed to do.

Since you've been fiddeling with it – do you have any other suggestions in terms of what you'd like to see in the API?

[jhermsmeier]

Closing this, since it's been fixed in #8, and some of the API suggestions have been incorporated