See:
http://www.rfc-editor.org/errata_search.php?rfc=5988&eid=3075

review whether quoting is necessary, etc.

See:
http://www.rfc-editor.org/errata_search.php?rfc=5988&eid=2630

Jim Schaad suggests that padding being zero is bad if AES-GCM ever loses its inviolate IND-CCA(2) status. That would open up some known plaintext attacks, probably similar to those that people are getting excited about with in RC4. I'm not concerned, but I think that it's worth checking to see if this is worth addressing.

A simple change would be to insist on all the octets being a repeat of the counter value, similar to how CMS does it (though CMS padding is 1-255 bytes because zero is not allowed for a reason I can't fathom).

application/problem+json has been suggested.

Discussion with Leif:

A general question: is there a requirement that the Key: header is the same
for all variations / alternate for a URL? Or can two responses from the origin
for a given URI have different Key: values?

This becomes important, because if there's no way for an origin to specify
that the Key: is fixed for a URI, we can't do much in ways of optimisations on
the cache. For example, if the Key: can be fixed for all alternates, it'd be
possible to produce a fast lookup table or hash for the alternates. If not,
you have to evaluate every single alternate in the cache for that URL until
you find one that satisfies the modifiers.

In the current design, they should (lower-case) be the same. It's probably worth making that a requirement, so you can rely upon it (except when the key changes, of course). We could even say that each URI has exactly one Key, and the latest value seen from the origin overwrites any previous value?

Interesting thought. So when the Key: changes, that is an implicit invalidation of all other alternates for that URL?

As per Martin's e-mail on list.

"accept-post" as it is currently defined in the draft-nottingham-link-hint draft works different from the current proposal in http://tools.ietf.org/html/draft-wilde-accept-post. it would be good to align the way in which these fields work. Currently, the "accept-post" of link hints allows a list of specific media types, whereas the Accept-Post header field may contain "media ranges".

This current draft and the ones preceding it appears to have such limited applicability as to be unusable for the majority of api use cases where JSON is used so I am wondering are JSON api's an intended use case for the draft?

It is fairly typical to return multiple problems when the JSON presented to a server cannot be processed. The canonical use case is a set of validation errors which have at least the following basic requirements:

• a problem description
• fine grained location in the request document where the problem exists (eg JSON field level granularity as described by json-pointer)
• machine processable problem class/type
• machine processable problem code/reason
• user related messages detailing the problem and how it may be rectified
• multiple problem support

The above requirements are fairly critical requirements for a viable JSON problem media type when dealing with JSON flavoured apis.

So my question, are JSON API's an intended use case for this draft or not?

I am fine if its "no", but if it is "yes", bare in mind that I do not regard "you can add anything you want to the payload" as an acceptable answer, as everyone may as well use their existing media type instead of surprising clients by switching media types to one such as this.

If the answer is "yes", please answer how this draft:

• assists JSON api clients to identify problem fields in their requests
• assists clients by switching to a different media type than that requested
• improves the likelihood of consistency by repeating HTTP status codes, given payload and headers may be produced by different operational layers (eg application server behind a reverse proxy)
• assists servers to communicate field and resource level validation errors to clients,
• assists clients to identify and process field level validation problems
• improves interoperability when servers would need to add implementation specific fields to the payload to meet minimum client processing requirements

I await your considered response.

currently, the text in appendix A makes statements about how extensions should be serialized, but the RNC schema does not attempt to capture those constraints. which may be fine, but it also may confuse readers when they try to match what the text is saying to what the schema is doing.
maybe this is touching upon the bigger issue of how extensibility is defined: is the extensibility essentially JSON-based and the XML syntax then has to reflect that in some form of JSONish structure? another approach could be to leave this open, so that for example users of the XML media type would be open to define XML-based extensions, but then these of course would have no easy mapping into a JSON variant.
this is probably the general problem (that's essentially the same for home documents) whether the extension model is based on one particular metamodel, and claims that all extensions must follow it (even if they might only be used in a serialization that's based on a different metamodel).
i guess in the end all this boils down to is bascially your "XML or JSON? Just choose!" blog post and its claim that a hybrid tends to look weird in places. the question then simply is how to manage/constrain the weirdness.
one possibility to avoid the "metamodels are us" conundrum could be to leave it open to extensions to define how they are supposed to be serialized in different metamodels. this includes the possibility that an extension would only say how it is serialized in JSON (or XML), and then there would be no reliable way to tell how it should be used in a different representation. this would avoid the need for a custom metamodel (or a preferred one such as JSON), but place the burden on extensions to explicitly define how they're supposed to be used in different serializations.

would it make sense to add a "home" link relation to the home document draft? if not, should the draft maybe suggest the use of an existing one to use when linking to a home document? "start" maybe isn't terrible when just looking at the name, but then again it seems to be more "first" than "home" when looking at the definition: "Refers to the first document in a collection of documents. This link type tells search engines which document is considered by the author to be the starting point of the collection." http://www.w3.org/TR/1999/REC-html401-19991224/types.html#type-links

It's likely necessary for the server to know which protocol the user agent has chosen, and perhaps even the hostname (for load balancing). At the very least, there should be a flag in SETTINGS that indicates that an alternate service has been used.

As per the draft's TODO.

Suggestion from Crocker:

This document standardises the mechanism for communicating the user's 
preference, but need not standardise its fine-grained semantic.  Simply 
put, the feature is a statement by (or on behalf of) the end-user of the sort 
"you have a 'safe' setting that you offer to users.  This user is hereby 
opting into that, according to your definition of the term."

alternate -> alternative, for Martin.

From Eric Lawrence:

The spec doesn’t clearly state what happens in the case that the original request didn’t match the key on the response (There’s language which implies that this rule means the response is not cacheable).

See:
http://www.rfc-editor.org/errata_search.php?rfc=5988&eid=3158

when working with the SemWeb/RDF community, it becomes obvious that link relations (and any other registries that manage concepts through non-URI identifiers) are a challenge for that community. even if they want to (re-)use those concepts, they cannot legally do so within RDF, because RDF requires identifiers to be URIs.
would it make sense to include something in RFC 5988bis that would allow RDF representations to use registered link relations as URIs? It would not be pretty to do that, because then on the web, registered link relations would be strings, and on the semantic web, they would be some form of equivalent URI. but maybe such a solution would be better than not doing anything, and making it impossible for RDF-based models to properly use registered link relations at all?

Discussion with Leif:

Section 2.1: In step 4, it says to case normalise all values to lower
case. How is that expected to work when a modifier asks for case sensitive
matching? 2.2.6 indicates that "c" reverts this, but that seems convoluted at
best (surely no implementation will do / undo the normalisation). I think step
4 should be clarified and say that the values can be lowercased or left as is
depending on the modifiers.

That means we'd need pairs of modifiers for case sensitive vs. insensitive.

I'm tempted to make it ALL case insensitive for now; thoughts?

I think case insensitive matches makes sense. Case sensitivity might make sense on e.g. some cookie values that are e.g. base-64'd… How likely that is to be used in a real implementation, I honestly don't know.

Something to consider to go along with the safe-hint. To allow a server to advertise that it offers a "safe" alternative to any given resource:

Link: <http://example.org>; rel="alternate"; safe

The implication here would be that by default, the given resource may not be safe, but that the "safe" alternative will be provided if "Prefer: safe" is included in the request.

The alternative is to use a "safe" link relation:

Link: <http://example.org/safe-alternative>; rel="safe-alternate"

The implication here is that the linked resource is a "safe" alternative to the context resource, regardless of whether "Prefer: safe" is included in the request.

This would greatly simplify the model and implementations (browsers are reluctant to keep all that extra state around).

Main downside would be that

Key: Foo, Bar

and
Vary: Foo, Bar

wouldn't mean the same thing any more (but I think that's just aesthetic).

I just discovered a bug in my implementation. This is a reminder to fix them.

A few questions (courtesy of @yoavweiss), that came up while discussing Resource Hints + Link interop:

What should the browser do if a response returns with both "Link" and "Set-Cookie" headers, assuming that the URLs to preload are on the HTML's domain? Should the browser send the request with the proper cookies set? What if "Set-Cookie" comes after the "Link"? Should the browser wait for "Set-Cookie" if the header parts of the response is still open (i.e. "\r\n\r\n" wasn't yet read from the socket)?

I think we should define that. The best compromise performance-wise is probably to respect cookies if they arrived before the "Link", but not guaranty respecting them afterwards.

(from Bjoern)

Given that

Within at most 14 days of the request, the Designated Expert(s) will
either approve or deny the registration request, communicating this
decision to the review list and IANA. ...

does not happen in practise, revising the registration process should be
a primary concern.

This issue includes discussion of how the registry should be managed, or not managed.

This isn't being used, and the use case it was created for doesn't seem to have materialised. Can / should we get rid of it?

As per draft TODO list.

Discussion with Ilya:

Cache dedup notwithstanding.. What do you think of:

Key: CH-DPR;pr=[1.5:]

Aka, allowing "pr" to operate on "naked" values, or optionally, if the name is provided on a specific field-> value? This would give it nice symmetry with other modifies in Key.

I like where this is going - if you want to use the body, you should
also define an XML version of this; if a client requests
application/xml, and the server encounters a problem, it seems weird to
send JSON back.

Why serialise this into a Link header ? Why not Problem-describedby,
Problem-title etc. ? For simple clients, that's much easier to deal
with.

I would have the following rules, so that clients have firmer ground to
stand on:
* Always send the problem back in the header
* If client asked for JSON or XML, send a body back that contains
the problem details as described in the draft; applications can
add more to that if they want to.

http://tools.ietf.org/html/draft-nottingham-httpbis-alt-svc-03#section-1

expressed a strong desire utilize

desire to?

from Kevin Smith on-list

Section 3.6:

" If the string "CONNECT" appears in alwaysDirect, it indicates that
requests that require establishment of a tunnel (e.g., for "https"
URLs) MUST NOT use the WPD's proxies, but instead ought to be made
directly to the origin (i.e., without a tunnel)."

IIRC CONNECT involves the proxy in the setup of the tunnel, in which case 'MUST NOT use the WPD's proxies' seems misleading. If the intention is that the request is that tunnelled requests are always direct, then maybe 'TUNNELLED' is a more appropriate value.

For the load balancing use case, it's necessary for clients to always flush altsvc cache upon a network change, but right now they're only required to examine the cache for suspicious entries. We should discuss whether this should be upgraded to always flush.

Logically, there are two functions for this header field:

• To describe the encryption (nonce and keyid)
• To describe the key derivation for a given keyid.

@bifurcation suggests that two header fields be used, if only to make the story a little easier to tell.

We can use the former to say: "assume a shared key with ID X", then the latter one can deal with the business of actually describing how that key can be derived. He also suggests that JWK is a useful construct for key description/conveyance.

a cache that implements the Key header field MUST NOT use a stored response unless all of the selecting header fields nominated by the Key header field match in both the original request (i.e., that associated with the stored response) and the presented request.

Above behavior dictates "AND" operation on all of the Key parameters. What about "OR"? For example, what if I wanted the response to be cached for multiple UA's - e.g. Android, iPhone.

Key: user-agent;s="Android";s="iPhone" (Android AND iPhone)
Key: user-agent;s="Android";o;s="iPhone" (Android OR iPhone)

First example is an implicit AND, and wouldn't be satisfied for any UA.. Whereas, what we're actually after is the second case, where we want the cache to serve the response to multiple different UA's. Q: is there a reason why "OR" is omitted in current spec? Could / should we add a parameter ("o" in above example) to support this?

for the JS people.

Some explicit text about how link cardinality would help; it's very tempting to limit cardinality in an API, but this limits how links can be used.

An appendix with suggested patterns for accessing links might be useful too.

Need guidelines for servers that use the Alt-Svc header field.

From the draft TODO.

Is it time to add a registry for the namespace of link parameters?

See:

• http://tools.ietf.org/html/draft-nottingham-link-hint
• http://tools.ietf.org/html/rfc6690

Flag to say "don't allow anything to leak onto the network"

RFC5988, 5.2:

 By default, the context of a link conveyed in the Link header field
 is the IRI of the requested resource.

This means that the Link in a request has a context of the requested resource. Using the request representation itself might be more sensible.

See:
http://httpwg.github.io/specs/rfc7231.html#identification

It might be useful to allow the WPD to pass proxy auth info to the proxy.

Likewise, it might be interesting to allow auto to be required to fetch the WPD. However, the UX for that would be difficult, if we want to get to something more than a modal dialog box.

Make it explicit that you can ignore Vary if you understand Key.

From Toronto discussion, this needs to be crystal-clear.

@steveklabnik, the person who is currently leading the efforts of developing the json-api spec suggested that I should post my concerns about the http-problem specification right at the source (I'm guessing that's here).

I've written a lengthy comment about it: json-api/json-api#7 (comment). It would be great if you were willing to discuss any improvements! (Here)

Currently, we aren't very precise about this. The actual information required is:

• the curve
• the point format
• an identifier for all of the above

Well done!

I was totally caught by surprise to see the document number ++, you made my day. =)

You can consider me an early adopter so I did some research trying to imagine where this might end up and this is the resulting document for your perusal.

The following considerations were made and guidelines followed:

1. I only reused items from existing specifications which I consider to be suitable additions. ymmv
2. The relevant references have been added sparingly with my illegal comments. Should you require more detail, I can oblige.
3. I chose to use URNs (RFC2141) instead to differentiate, between type identifiers and links.
4. I've added a header "property" as per RFC6415, with general links which relate to all resources.

The result is speculative only in hope to be utilized as a basis for further discussion which I'll continue on list @apps-discuss unless you have another preference.

{
  "expires":"2012-06-07T09:30:00Z", 
  "urn:fooapi:property": {             // urn RFC2141 RFC6415 
    "titles":{
      "default":"FOO Api",
      "en-us":"FOO Api"
    },
    "type": "http://protocol.example.net/version",                     
    "copyright": "http://example.com/copyright",                       
    "version": "0.1.0",                                                
    "license":{                                   //RFC 4946 
      "type": "application/rdf+xml",
      "href": "http://creativecommons.org/licenses/by-nc/2.5/rdf"
    },
    "disclosure": {                               //RFC 6579
      "href": "http://example.org/ipr/meta-spec",
      "title": "Patent Disclosures List"
    },
    "hub": {"href": "http://example.com/hub"},                         
    "monitor": {                                  //RFC 5989
      "href": "http://www.example.com/pet-profiles/alpacas/",          
      "hinst":{
        "allow": ["GET", "SUBSCRIBE", "PUBLISH"]
    },
    "lrdd": {"href-template": "http://example.com/lrdd{?uri}"},     
    "author": {"href-template": "http://example.com/author{?uri}"}, 
    "edit": {
      "href": "http://example.com/edit{?uri}",
      "hints": { "allow": ["GET"], "representations": ["text/html"]}
     }
  },
  "resources": {
    "urn:fooapi:widgets": {
      "href": "/widgets/",
      "paging": {          //RFC 5005 5988
        "link": {         
          "rel": "prev",
          "title": "Prev",
          "hreflang": "en",
          "media": "all",
          "charset": "utf-8",
          "type": "application/json",
          "href-template": "{?offset,limit}",
          "href": "?offset=0&limit=10"
        },
        "link": {        
          "rel": "next",
          "title": "Next",
          "hreflang": "en",
          "media": "all",
          "charset": "utf-8",
          "type": "application/json",
          "href-template": "{?offset,limit}",
          "href": "?offset=20&limit=10"
        },
        "link": {        
          "rel": "section",
          "title": "Section",
          "hreflang": "en",
          "media": "all",
          "charset": "utf-8",
          "type": "application/json",
          "href-template": "{?section}",
          "href": "?section=10"
        },
        "start": "http://example.com/start",
        "current": { "href": "./"},
        "last": "http://example.com/last",
        "first": "http://example.com/first"
      },
      "hints": {
        "allow": ["GET", "POST", "PUT", "DELETE"],
        "representations": ["application/json","text/html"],
        "accept-language": ["en"],
        "accept-post": ["application/json"]
      }
    },
    "urn:fooapi:widget": {
      "titles":{
        "default":"The Widgets API", 
        "nl":"Het Widgets API", 
      }, 
      "href-template": "/widgets/{widgetId}",
      "href-vars": {
        "productRoomId": "urn:fooapi:param@widgets"
      },
      "revisions": {        //RFC 5829
        "version-history": "/widgets/{widgetId}/revisions",           
        "latest-version": "/widgets/{widgetId}/latest",               
        "working-copy": "/widgets/{widgetId}/draft",                  
        "working-copy-of": "/widgets/{widgetId}/draft-of" ,           
        "predecessor-version": "/widgets/{widgetId}/prev",         
        "successor-version": "/widgets/{widgetId}/next"              
      },
      "hints": {
        "allow": ["GET", "PUT", "DELETE", "PATCH"],
        "representations": ["application/json", "text/html", "application/json-home"],
        "accept-patch": ["application/json-patch"],
        "accept-put": ["application/json"],
        "accept-ranges": ["bytes"],
        "prefer": ["return-asynch", "return-minimal", "return-representation", "wait", "strict", "lenient"],
        "docs": "http://example.com/docs", // help?? [W3C.REC-html401-19991224](http://www.w3.org/TR/html5/links.html#link-type-help)
        "precondition-req": ["etag", "last-modified"],
        "auth-req": [{ "scheme": "Basic","realms": ["private"]}],
        "status": "development"
      }
    }
  }
}

The discriminator string probably isn't needed since we munge the CEK with a string that has a similar function. And the record index is part of the IV.

Jim Schaad is convinced that you need to roll the tag from the previous block in to prevent substitution attacks, but I think you are screwed at that point anyway.

Run by @ekr first.

5988 specifies links in terms of IRIs. Is this the right thing, or should they be URIs?

listed as application/json-problem but then the sub-type is declared as problem+json

the HTTP problem draft currently defines standalone structures in JSON and XML, intended to be served as responses with their own media type. maybe it would be helpful to address the question whether the JSON or XML also could be embedded in other media types. i guess technically there's nothing the draft could do to disallow this. but it might be interesting to address this question openly and answer it, so that people wondering about this might find some guidance.

Draft looks ok initially... a couple of points, however:

1. Consider using the name Cache-Key instead of just Key. There are many types of keys and it's better to be clear and specific.
2. The predicate syntax seems rather complicated. In theory it's fine but I'm having a difficult time imagining people using this in practice even for simple cases and can imagine a number of ways where it could go wrong. Especially since we have a hard enough time getting people to use vary properly as it is.

From Nicolas mailhot:

It would be really nice if the spec mandated that special networks (as defined in rfc 6761 and 6762) are not proxyfied by default unless an override exists in the wpd (for people doing strange things with local proxies).

I'm sure most proxy operators are sick of needing to tell web clients 127.0.0.x is local for example…