ExternalVendorCode/tahoe-lafs
1
0
Fork 0
mirror of https://github.com/tahoe-lafs/tahoe-lafs.git synced 2025-04-13 22:03:04 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Specify preferred encoding and encoding negotiation

Browse Source
This commit is contained in:
Jean-Paul Calderone 2018-06-06 13:46:45 -04:00
parent b8cfee79e3
commit c3011a434b
1 changed files with 24 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

26
docs/proposed/http-storage-node-protocol.rst
View File

@ -210,8 +210,26 @@ and shares.
A particular resource is addressed by the HTTP request path.
Details about the interface are encoded in the HTTP message body.
JSON is used throughout for the examples but is likely not the preferred encoding.
The structure of the examples should nevertheless be representative.
Message Encoding
~~~~~~~~~~~~~~~~
The preferred encoding for HTTP message bodies is `CBOR`_.
A request may be submitted using an alternate encoding by declaring this in the ``Content-Type`` header.
A request may indicate its preference for an alternate encoding in the response using the ``Accept`` header.
These two headers are used in the typical way for an HTTP application.
The only other encoding support for which is currently recommended is JSON.
For HTTP messages carrying binary share data,
this is expected to be a particularly poor encoding.
However,
for HTTP messages carrying small payloads of strings, numbers, and containers
it is expected that JSON will be more convenient than CBOR for ad hoc testing and manual interaction.
For this same reason,
JSON is used throughout for the examples presented here.
Because of the simple types used throughout
and the equivalence described in `RFC 7049`_
these examples should be representative regardless of which of these two encodings is chosen.
General
~~~~~~~
@ -424,6 +442,10 @@ Just like the immutable version.
.. _RFC 7469: https://tools.ietf.org/html/rfc7469#section-2.4
.. _RFC 7049: https://tools.ietf.org/html/rfc7049#section-4
.. _CBOR: http://cbor.io/
.. [#]
The security value of checking ``notValidBefore`` and ``notValidAfter`` is not entirely clear.
The arguments which apply to web-facing certificates do not seem to apply