[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [Captive-portals] API access and .well-known

On 1/14/18 9:39 PM, Martin Thomson wrote:
(see also https://github.com/capport-wg/api/issues/2)

Currently the API draft proposes use of .well-known for finding the
API.  Generally speaking, there's a trend toward avoiding use of
.well-known except when either:

* it is difficult to configure or provide a full URL, or
* the .well-known provides information about the origin as a whole.

In this case, the latter definitely doesn't apply, but I think we
should probably discuss the former a little.

The problem we have is that there are really two URLs we care about
and 7710 only provides one.  (PvD might provide two URLs, so we don't
need to worry about this problem for PvD.)

The old API draft used HTTP method to distinguish the two uses: GET
for HTML that you might show to a person; POST for an API.  But the
new, leaner API uses GET too, so that's not an option we can use.

HTTP content negotiation is another option here.  It's pretty
well-supported on the whole aside from a few wrinkles around caching.
I suspect we will find that caching will be infeasible for other
reasons (see the other issues on GitHub for a taste of that).  Content
negotiation works [1] by having the client send an Accept header field
with a new media type (straw man: application/capport+json) and the
server would detect this and send back an API response or redirect to
the API endpoint.  If this content-type wasn't present, it could send
back HTML (or a redirect to a server that does).

Here's the options I see:

a. use .well-known and just provide better justification for it
b. use content negotiation
c. find some way to get two URIs, like revising 7710 or finding an
alternative mechanism (such as the one in RFC 5986)

Tommy notes that this has a drawback in that it forces the web UI and
API to be co-located.  I don't think that is necessarily true if you
accept that HTTP-level redirects are possible.  Indeed, that is how
many enforcement points work today: they terminate a connection
locally but then redirect to more capable servers.  Also, using
.well-known doesn't really make the resources any less co-located
because the origin - and the server - are still the same.

What do folks prefer here?

[1] Content negotiation can use other properties of the request as
well, but Accept is common and pretty widely supported.
We would definitely prefer to see 2 distinct urls here. It makes the least amount of assumptions, and gives the most amount of flexibility.