Recommend html landing page?

[cholmes]

Just came across https://franklin.nasa-hsi.azavea.com/ and it's got a really nice html landing page.

And reminded me that I really like that OGC API - Features often have html landing pages. But when you give people a root stac URL it's usually a bunch of JSON.

I'd ideally like to make some 'strongly recommended' thing to have people put an html page at their root catalog as the default, with a link (rel alternate) to the json (which would rel alternate html back). This could just be a stac browser (though we'd need to figure out how it can do rel alternate to the json if it doesn't already), or it could be an overview page like franklin.

[philvarner]

One challenge here is that it would prevent a user from easily looking at the JSON responses in the browser. I do this a lot.

It seems that Franklin no longer has this page, maybe for that reason? @jisantuc

One thing we seem to be missing in the the Core text docs (but is in the openapi.yaml) is that a user should implement the rel service-docs, which can be nice landing page. This example https://eod-catalog-svc-prod.astraea.earth/api.html is redoc with a little customization (logo, front text, etc).

[cholmes]

I don't think it'd prevent easily looking at the JSON responses. Indeed I'd put in a recommendation to have a clear link to it. I like how pygeoapi does it https://demo.pygeoapi.io/master

Emphasizing rel service-docs a bit more does make sense to me as well, though I feel like a landing page is more links to the collections, overview of the data that is there.

[philvarner]

That seems to use an additional query parameter "f=json", which we'd have to define. I'd don't necessarily like that, since then there's Accept and f to process.

[jisantuc]

One challenge here is that it would prevent a user from easily looking at the JSON responses in the browser. I do this a lot.

That's part of why we removed it. I told people a few times about Chrome and Firefox extensions that let them set the Accept header, and that was a nuisance, so it's gone.

The other reason is that we only got through the landing page and never got to the rest of the HTML views, and also maintaining the twirl templates for the default views wasn't going to be fun / wasn't super useful for anyone not really comfortable in Scala. We have a follow-up issue that I think is a better fit -- azavea/franklin#519. In that issue, the goal is to support pluggable frontends basically, where you tell the server where the frontend lives and it serves it on <wherever the host is>/app or something. I don't think it's true that there's one best frontend that servers should pick in advance, and also people will have different kinds kinds of data that should show different things. The pluggable frontend lets the spec focus on the API routes and models and lets users plug whatever is appropriate for their uses.

On a related note, sorry for sweeping the "nice html landing page" out from under your link in the issue description @cholmes

[cholmes]

I'm ok to have this closed for beta.2, but I'm not giving up on this completely. At the very least I do think we should recommend a rel=alternate type=html so that people who get handed a json can actually find an html version of it.

And OGC API - Features recommends that implementations implement both their GeoJSON and HTML conformance classes.

That seems to use an additional query parameter "f=json", which we'd have to define. I'd don't necessarily like that, since then there's Accept and f to process.

I don't think you have to do it that way, that's just how that implementation did it. I think you just need the rel=alternate links between the two. I guess I don't care that the root URL defaults to JSON, but I think implementations should provide a link to an html view. It could just be stacindex for the 'easy' case.

We have a follow-up issue that I think is a better fit -- azavea/franklin#519. In that issue, the goal is to support pluggable frontends basically, where you tell the server where the frontend lives and it serves it on /app or something.

Yeah, something like that would make sense to me. I don't care about the server itself rendering the html - I care that the JSON response gives at least one html alternate link.

One challenge here is that it would prevent a user from easily looking at the JSON responses in the browser. I do this a lot.

I don't understand this - how are users prevented from easily looking at JSON responses in the browser? I too do this a lot, but I've never had a problem with seeing the JSON responses from an OGC API - Features service, they all have a link. We just say that the html response should have a link to the JSON response.

[jisantuc]

We just say that the html response should have a link to the JSON response.

I think this makes sense but also that in a world with non-standardized frontends maintainers will have to tell people pretty often where the JSON link is since different frontends will put it different places. I think the API spec should say as little as possible about what's on the HTML pages, and I think that's very little -- verification HTML page content verification will be much harder than data contract verification in the JSON endpoints

[philvarner]

My view is that if people want to implement this then fine, but the API spec doesn't need to say anything about it.

[m-mohr]

Do we mention alternate links anywhere in the API spec? That could go in there with a recommendation to provide them, e.g. for HTML. Otherwise, I think we don't need to do more. People nowadays seem to use the STAC Browser demo instance a lot for HTML rendering, even more than STAC Index, it seems. ;-)