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

[Tommy Pauly <tpauly@apple.com>]

Hi Evert,

I think that all three options that Martin provided implicitly support two different URLs ([API-URL] and [HTML-URL] for lack of a better term) that a client device could use. I agree that making things very explicit and clear is important.

>> a. use .well-known and just provide better justification for it

The reason I suggested a well-known URL was to ensure that we didn’t collide with some other URL (like the captive portal landing page) or some other JSON that’s not really doing this API. It would be easier to validate that the configuration did indeed intend to point to this JSON API. 

Note that in this setup, you would learn about the URL of the Captive Portal JSON API as the main entry point for the UE (the discovery coming from either 7710 or PvD or the like). This is specifically the first URL, [API-URL]. The JSON content itself would contain [HTML-URL].

Instead of using a well-known URL here, we could imagine just enforcing that the discovered URL MUST be a JSON endpoint that serves up this API.

The benefit of this approach (get [API-URL] first, and follow it to [HTML-URL]) is that we pave the way towards more flexibility when we don’t necessarily need the [HTML-URL] to do traditional captive portals, but instead can do interaction models designed for watch-like devices, or multiple devices that don’t ever need a follow-on URL.

>> b. use content negotiation

In this approach, [API-URL] and [HTML-URL] are essentially the same, just with different content. I agree with the concern that this is ambiguous. It also has the potentially negative effect of tying together the JSON API and traditional HTML URL. Yes, you can do redirects, etc, to not be co-located, but this seems more prone to configuration error and complexity. 

>> c. find some way to get two URIs, like revising 7710 or finding an
>> alternative mechanism (such as the one in RFC 5986)

I think that this approach is effectively saying that [API-URL] and [HTML-URL] are both signaled explicitly in the discovery mechanism. While this avoids the problem of ambiguity, it bakes in the notion of a legacy captive portal URL, and takes up more space in the discovery mechanism.

I’d vote for some variation on (a), but we can just explain the meaning of the URL we discover more clearly, instead of using a well known URL.

Thanks,
Tommy

> On Jan 16, 2018, at 10:16 AM, Evert Pot <evert@yelp.com> wrote:
> 
> 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.
> 
> Evert
> 
> _______________________________________________
> Captive-portals mailing list
> Captive-portals@ietf.org
> https://www.ietf.org/mailman/listinfo/captive-portals