search

opengeospatial / ogcapi-styles

A Web API that enables map servers, clients as well as visual style editors, to manage and fetch styles.
https://ogcapi.ogc.org/styles
Other
10 stars 5 forks source link

Add additional GET endpoints #49

Open jyutzler opened 2 months ago

jyutzler commented 2 months ago

Clients should not be forced to perform multiple GET requests if they know what they want. The current behavior is:

  1. GET {baseResource}/styles/{styleId}
  2. Inspect the response and find the link with a rel of "stylesheet" and the appropriate type
  3. GET the corresponding href

This is annoying. Condense this into one step by adding GET {baseResource}/styles/{styleId}/stylesheet?type=... or GET {baseResource}/styles/{styleId}/{type}.

We can also add endpoints for the singleton _rel_s:

I want to keep the existing behavior for discoverability purposes as the client will not necessarily know which type is available.

cportele commented 2 months ago

The issue is not clear to me.

If a client does not know what it wants, the flow is as follows:

  1. GET {baseResource}/styles
  2. Inspect the response and find the style the client is looking for and then select the link with rel "stylesheet" and a type that the client can handle.
  3. GET the corresponding href

If the client knows the style URI or id, it can directly GET {baseResource}/styles/{styleId} with an Accept header that identifies the style encodings / media types supported by the client and their priorities. The client will receive the best match or a 406 response.

There is, of course, the issue that none of the style encodings have registered a media type with IANA. The approach has been to use media types in the vnd branch (that theoretically OGC could also register) and include a media type definition for style encodings that are normatively referenced.

jyutzler commented 2 months ago

It looks like I got a few things wrong when reviewing the API.

Given this, I make the following recommendations: