RFC: Documenting JSON media type changes

[chris...@gmail.com]

Over in the tiddlywikidev group

https://groups.google.com/d/topic/tiddlywikidev/jjha5iXYFo4/discussion

some dicussion about dragging and dropping tiddlers into TW5 led to a
realization that was a (sort of) bug in TiddlyWeb

https://github.com/tiddlyweb/tiddlyweb/issues/99

A fix has been made on this branch

https://github.com/tiddlyweb/tiddlyweb/compare/x-tiddler%2Bjson

The remaining task that needs to be completed before this can be
merged and released is to determine and then do the level of required
changes to the documentation. I think there are a few options, which
I've listed below, but first a bit of a summary (see the links above
for more details):

The bug is that if you store a tiddler with a `type` attribute of
`application/json` when you `GET` that tiddler as `application/json`
the body of the response will be the value of the `text` attribute (as
JSON). Prior to the changes there was _no_ way to get the JSON
representation of the full tiddler at the standard tiddler URI.

The fix is that if you store in the form described above, you can get
the full tiddler representation as JSON by setting an 'Accept' header
of `application/vnd.tiddlyweb+json` (or use the `.json` extension on
the request). The response will still be `application/json`.

`application/json` in the Accept header continues to work as before.

The `application/vnd.tiddlyweb+json` media type can be used in any
request (on any URI) that would previously normally have used
`application/json` in the past.

Thus some question arise: To what extent does this need to be made
official? Should `application/json` be deprecated for all requests in
favor `application/vnd.tiddlyweb+json` or should we just note somewhere
that it is available if you are working in a context where there may
be tiddlers with a type attribute of `application/json`?

Once those questions are answered we need to choose to what extent the
change is documented. The answers above drive these options:

* Make a quick note on http://tiddlyweb.tiddlyspace.com/ [1] about the
issue with the type attribute and leave things be.

* Change the pydoc within the code so that any reference to
`application/json` is audited to see if it should be
`application/vnd.tidlyweb+json` and change where needed (this will
also update the docs at http://tiddlyweb.readthedocs.org/ ).

* Do a similar audit and update at http://tiddlyweb.tiddlyspace.com/

Obviously the first option requires the least effort. This is an
important concern if it is just me that will be doing the work. If
other people will be involved, the 2nd and 3rd may be more
approachable.

Opinions? Please make sure you understand the issue (by reading the
various links) if you want to keep things on topic.

Thanks for any input.

[1] With the current lack of proactive development and support on
tiddlyspace.com I'm a bit concerned that it may be necessary to move
the docs from there to somewhere else. I'd rather not do this as it
would be yet another move of the documentation.

As things stand much of the text in @tiddlyweb is not being rendered
to readable HTML. Many of the tiddlers are in tiddlywikitext. With
twikifier down an error message with raw text is presented. Also,
several pieces of code (notably tiddlyweb itself, tiddlywebwiki, the
markdown plugin, the links plugin, the csrf plugin) have advanced
since last year so TiddlySpace is slowly falling behind modern
standards.

--
Chris Dent http://burningchrome.com/
[...]

[Jeremy Ruston]

Hi Chris

The second option would be better but if it's not doable with the resource available then I guess option one will have to suffice. With reference to TiddlySpace ideally there wouldn't be any dependency between the TiddlyWeb project and the TiddlySpace service.

Best wishes

Jeremy

--
You received this message because you are subscribed to the Google Groups "TiddlyWeb" group.
To unsubscribe from this group and stop receiving emails from it, send an email to tiddlyweb+unsubscribe@googlegroups.com.
To post to this group, send email to tidd...@googlegroups.com.
Visit this group at http://groups.google.com/group/tiddlyweb.
For more options, visit https://groups.google.com/d/optout.

--
Jeremy Ruston
mailto:jeremy...@gmail.com

[chris...@gmail.com]

On Wed, 7 May 2014, Jeremy Ruston wrote:

> The second option would be better but if it's not doable with the resource
> available then I guess option one will have to suffice. With reference to
> TiddlySpace ideally there wouldn't be any dependency between the TiddlyWeb
> project and the TiddlySpace service.

Thanks for the comments Jeremy. Do you have any thoughts on this
aspect:

>> Thus some question arise: To what extent does this need to be made
>> official? Should `application/json` be deprecated for all requests in
>> favor `application/vnd.tiddlyweb+json` or should we just note somewhere
>> that it is available if you are working in a context where there may
>> be tiddlers with a type attribute of `application/json`?

[Jeremy Ruston]

Hi Chris

Thus some question arise: To what extent does this need to be made
official? Should `application/json` be deprecated for all requests in
favor `application/vnd.tiddlyweb+json` or should we just note somewhere
that it is available if you are working in a context where there may
be tiddlers with a type attribute of `application/json`?

I think there's less confusion if consumers of the API can be directed to use application/vnd.tiddlyweb+json, with a note that application/json is provided for backwards compatibility, at the cost of some limitations.

Best wishes

Jeremy

 

--
Chris Dent                                   http://burningchrome.com/
                                [...]

--
You received this message because you are subscribed to the Google Groups "TiddlyWeb" group.
To unsubscribe from this group and stop receiving emails from it, send an email to tiddlyweb+unsubscribe@googlegroups.com.
To post to this group, send email to tidd...@googlegroups.com.
Visit this group at http://groups.google.com/group/tiddlyweb.
For more options, visit https://groups.google.com/d/optout.

[chris...@gmail.com]

On Wed, 7 May 2014, Jeremy Ruston wrote:

> The second option would be better but if it's not doable with the resource
> available then I guess option one will have to suffice. With reference to
> TiddlySpace ideally there wouldn't be any dependency between the TiddlyWeb
> project and the TiddlySpace service.

Ideally, yes, which is just stupid, of course, because we created that
service to be reliable, available to anyone and everyone and have some
longevity. Feh.

I've posted in the tiddlyspace group looking for some feedback on the
possibility of getting twikifier fixed.

If that doesn't get me anywhere I guess I'll move the docs back to my
VM where I already have twikifier running for Tank. twikifier is the
limiting factor (makes it more complex for free or nearly free
infrastructrue services).

In better news I've merged the applicaiton/vnd.tiddlyweb+json changes
to master and updated the small amounts of code-associated docs that
referred to media type. It turns out the specific talk of how to make
API requests is in the (currently mostly broken) online docs.

[chris...@gmail.com]

On Fri, 9 May 2014, chris...@gmail.com wrote:

> In better news I've merged the applicaiton/vnd.tiddlyweb+json changes
> to master and updated the small amounts of code-associated docs that
> referred to media type. It turns out the specific talk of how to make
> API requests is in the (currently mostly broken) online docs.

I've:

* released tiddlyweb 2.3.0 with the media type changes
* bandaid fixed tiddlyspace
* updated the docs on http://tiddlyweb.tiddlyspace.com/ to reflect the
new media type