aboutsummaryrefslogtreecommitdiff
path: root/doc/api.md
diff options
context:
space:
mode:
authorLinus Nordberg <linus@nordberg.se>2021-05-04 16:08:22 +0200
committerLinus Nordberg <linus@nordberg.se>2021-05-04 16:08:22 +0200
commit9ee06539685bdcaea84b3daede5354d83264c1e4 (patch)
treee26e367fefc4c98367929d0a8548437a499c5684 /doc/api.md
parentc163da97d32a291a1c913800c926d7758c641c6e (diff)
explain how input and output data are sent
This is the "header in, body out" idea written up. We might change to a "POST body in, receive body out" scheme with "Content-Type: application/stfe" if we can decide that POST is not a terrible idea after all.
Diffstat (limited to 'doc/api.md')
-rw-r--r--doc/api.md10
1 files changed, 10 insertions, 0 deletions
diff --git a/doc/api.md b/doc/api.md
index 362dc46..c747aa2 100644
--- a/doc/api.md
+++ b/doc/api.md
@@ -141,6 +141,16 @@ that it must be a valid HTTP(S) URL that can have the `/st/v0/<endpoint>` suffix
appended. For example, a complete endpoint URL could be
`https://log.example.com/2021/st/v0/get-signed-tree-head`.
+Input data (in requests) is sent as ASCII key/value pairs as HTTP
+entity headers, with their keys prefixed with the string
+`stlog-`. Example: For sending `treee_size=4711` as input a client
+would send the HTTP header `stlog-tree_size: 4711`.
+
+Output data (in replies) is sent in the HTTP message body in the same
+format as the input data, i.e. as ASCII key/value pairs on the format
+`Key: Value`. Example: For sending `tree_size=4711` as output a log
+would send an HTTP message body consisting of `stlog-tree_size: 4711`.
+
The HTTP status code is 200 OK to indicate success. A different HTTP status
code is used to indicate failure. The log should set the "error" key to a
human-readable value that describes what went wrong. For example,