search

metabrainz / web-service-v3-design

A collaborative specification for the third version of the MusicBrainz web service
2 stars 1 forks source link

Render text/html for annotations? #4

Open ocharles opened 12 years ago

ocharles commented 12 years ago

The annotation end point could also be extended to Accept: text/html, in order to produce rendered annotations. This might be useful to some people, but specifically useful to the web-site if we want to start dog fooding our own web service.

warpr commented 12 years ago

Our website will have a renderer available, so does not benefit much from annotations in text/html.

I imagine the only clients who would be interested in the source text of an annotation is a read/write client which provides end-users the ability to edit / write annotations. I think by far the more common request will be a request for the most recent version of the annotation, pre-rendered and ready to use in text/html.

I fear not making this available through json will cause considerable frustration for client developers with inflexible REST client libraries. So, while this seems like good enough for a first version, I fully expect we will be forced to add a text/html annotation embedded in a json response sooner rather than later.

mayhem commented 12 years ago

I think this is fraught with peril. I think there could be much bike shedding around what the HTML should look like that we output. How does CSS fit into this?

In general, this feels like conflating a markup/data layer with a presentation layer to me. I do, however, see the usefulness of it.

warpr commented 12 years ago

Thinking about it a bit more, what client developers probably expect is some kind of standard format. It doesn't necessarily have to be text/html. Markdown or reStructuredText would be suitable candidates, or even just mediawiki formatting. But our annotations use a subset of mediawiki formatting, which is going to be difficult for clients to render properly.

ocharles commented 12 years ago

I just want to clarify that I said it could be /extended/ to offer this Content-Type, not that this would be the only Content-Type. I think that whatever format our wiki docs in should be the default, unless you ask for another format.

I think there could be much bike shedding around what the HTML should look like that we output. How does CSS fit into this?

The HTML looks like the result of $formatter->render($annotation->text), and nothing more. CSS depends on how you want to style it, that's not got much to do with the web service.