rehash/doc/rest-api.tm

<TeXmacs|1.99.16>

<project|rehash.tm>

<style|tmmanual>

<\body>
  <todo|Is this actually REST?>

  <todo|Will this actually be used?>

  <todo|Implement>

  <todo|maybe authentication>

  <todo|error codes are incomplete>

  <\explain>
    <samp|/v0/insert-mapping/INPUT_HASH/OUTPUT_HASH>
  <|explain>
    Using the POST method, a hash mapping can be inserted. The Content-Type
    of inserted data must be <samp|application/json>. Only UTF-8 has to be
    supported as character encoding. The JSON should have the following
    structure:

    <\verbatim>
      {

      \ \ "expiration-time": EXPIRATION_TIME,

      \ \ "anonymity-level": ANONYMITY_LEVEL,

      \ \ "content-priority": CONTENT_PRIORITY,

      \ \ "replication-level": REPLICATION_LEVEL,

      }
    </verbatim>

    Where <var|EXPIRATION_TIME> is in microseconds since the epoch,
    <var|ANONYMITY_LEVEL>, <var|CONTENT_PRIORITY> and <var|REPLICATION_LEVEL>
    are integers in the (inclusive) range
    <math|<around*|[|0,2<rsup|32>-1|]>>, and <var|INPUT_HASH> and
    <var|OUTPUT_HASH> are textual encodings of the hashes to insert.

    <paragraph|Error codes>Unless specified otherwise, no response body is
    defined yet, although future revisions of this API may include one.

    <\description>
      <item*|201 Created>The server has inserted the mapping into rehash.

      <item*|202 Accepted>The server will insert the mapping into rehash, but
      doesn't feel like waiting until this operation is completed.

      <item*|400 Bad Request>The request was not understood, e.g. due to an
      unsupported hash types.
    </description>
  </explain>

  <\explain>
    <samp|/v0/query/OUTPUT_HASH_TYPE/INPUT_HASH>
  <|explain>
    Using the POST method, one can search for mappings. The Content-Type of
    the request body must be <samp|application/json>. Only UTF-8 has to be
    supported as content encoding. The JSON should have the following
    structure:

    <\verbatim>
      {

      \ \ "anonymity-level": ANONYMITY_LEVEL,

      }
    </verbatim>

    The client must list UTF-8 as accepted character encoding, and
    <samp|application/json> as accepted Content-Type. The output is a stream
    of JSON objects:

    <\verbatim>
      {

      \ \ "expires": EXPIRATION_TIME,

      \ \ "output": OUTPUT_HASH,

      }
    </verbatim>

    Other fields may be defined in the future.

    As a convenience to the client, each object must be on a line of its own,
    where lines are separated by line feeds \<backslash\>n and/or carriage
    returns \<backslash\>r. This request can take infinite time to complete,
    and possibly have a theoretically infinite output. As such, the server
    should probably consider the result uncachable.

    <\description>
      <item*|200><todo|is this correct?>
    </description>
  </explain>

  <\explain>
    <samp|/v0/insert>
  <|explain>
    Using the POST method, a hash mapping can be inserted. The Content Type
    must be <samp|application/json>. Only UTF-8 has to be supported as
    content encoding. The JSON should have the following structure:

    <\verbatim>
      {

      \ \ "input": INPUT_HASH,

      \ \ "output: OUTPUT_HASH,

      \ \ "expiration-time": EXPIRATION_TIME

      \ \ "anonymity-level": ANONYMITY_LEVEL,

      \ \ "content-priority": CONTENT_PRIORITY,

      \ \ "replication-level": REPLICATION_LEVEL,

      }
    </verbatim>

    Where <var|EXPIRATION_TIME> is in microseconds since the epoch,
    <var|ANONYMITY_LEVEL>, <var|CONTENT_PRIORITY> and <var|REPLICATION_LEVEL>
    are integers in the (inclusive) range
    <math|<around*|[|0,2<rsup|32>-1|]>>, and <var|INPUT_HASH> and
    <var|OUTPUT_HASH> are textual encodings of the hashes to insert.
  </explain>

  <\explain>
    <samp|/v0/add?in=INPUT_HASH_TYPES&out=OUTPUT_HASH_TYPES>
  <|explain>
    Using the POST method, a file can be uploaded, to be inserted into GNUnet
    FS and rehash. The input and output hash types are specified in the
    comma-separated lists <var|INPUT_HASH_TYPES> and <var|OUTPUT_HASH_TYPES>.

    <paragraph|Optional parameters for query string>

    The server should define some reasonable defaults. It is recommended the
    client sets the User-Agent string appropriately (e.g. <samp|Guix
    substitute> or <samp|Guix build>) if not all parameters are set.

    <\description>
      <item*|<var|expiration-time>>See <samp|/v0/insert>

      <item*|<var|anonymity-level>>See <samp|/v0/insert>

      <item*|<var|content-priority>>See <samp|/v0/insert>

      <item*|<var|replication-level>>See <samp|/v0/insert>
    </description>

    <paragraph|Request headers>

    <\description>
      <item*|Content-Type>For uploading a single file, specify
      <samp|application/octet-stream>, and send this file as request body.

      <todo|how to upload directories? Perhaps multipart/x-nar or
      application/x-directory Or look at https://doc.ipfs.io/reference/http/api/#api-v0-add?>

      <todo|If on the same machine, perhaps pass a file descriptor?>

      <item*|Accept-Charset>Ask for UTF-8

      <item*|Accept>Ask for <samp|application/json>
    </description>

    <paragraph|Response headers>

    <\description>
      <item*|Content-Type><samp|application/json> (on success)

      The response has the following structure:

      <\verbatim>
        {

        \ \ "hashes": [ HASH_A, <text-dots> ]

        }
      </verbatim>

      Where <var|HASH_A> <text-dots> are hashes of type
      <var|INPUT_HASH_TYPES>, <var|OUTPUT_HASH_TYPES>. Other fields may be
      defined in the future.
    </description>

    <paragraph|Error codes>

    <\description>
      <item*|201 Created>The server has inserted the file into GNUnet FS and
      rehash.

      <item*|202 Accepted>The server will insert the file into GNUnet FS and
      and rehash, but doesn't feel like waiting until this is completed.

      <item*|400 Bad Request>This request was not understood, e.g. due to
      unknown hash types
    </description>

    <\remark>
      The kitchen sink <samp|/v0/download/HASH> is more general.
    </remark>
  </explain>

  <\explain>
    <samp|/v0/download/HASH>
  <|explain>
    Using the GET method, the client can try to download a file from its
    hash. Using the POST method, the client can make additional demands.

    <paragraph|Request body (for POST, <samp|application/json>)>

    <\verbatim>
      {

      \ \ "parallel-downloads": [{"url": url} <text-dots>],

      \ \ "dowload-anonymity": integer (\<less\> <math|2<rsup|32>>)

      \ \ "upload": {see <samp|v0/add>},

      \ \ "return?": true/false,

      \ \ "verify-certificates?": true/false,

      \ \ "input-hash-types": [INPUT_HASH_TYPE, <text-dots>],

      \ \ "output-hash-types": [OUTPUT_HASH_TYPE, <text-dots>],

      }
    </verbatim>

    The fields <var|parallel-downloads>, <var|upload>, <var|return?> and
    <var|verify-certificates?> are optional. <var|upload> defaults to false,
    <var|return?> to true and parallel-download to an empty list. No default
    is specified for <var|verify-certificates?>. <var|HASH> may be
    <samp|none> if <var|upload> is set and <var|input-hash-types> and
    <var|output-hash-types> is set.

    If <var|parallel-downloads> is set, it is suggested to the server that
    the resource may be available at the passed URLs. This can be useful if
    the file isn't well-represented in GNUnet FS and rehash yet. The server
    MUST NOT ignore URLs it doesn't support, but return a ??? instead.

    If <var|upload> is set, the server is requested to upload the downloaded
    request to GNUnet FS and rehash, using the hash types
    <var|INPUT_HASH_TYPE> <text-dots> and <var|OUTPUT_HASH_TYPE> <text-dots>.

    If <var|return?> is false, the server MUST NOT return the actual file.

    The option <var|verify-vertificates?> specifies whether certificates
    should be verified. Set this to false if you're a time-traveller or the
    servers aren't in the certificate store.

    <\remark>
      The passed URLs should support range requests, and should agree on the
      content. If not, be prepared for trouble.
    </remark>

    <\remark>
      This endpoint should support range requests.

      <todo|are range-requests allowed with POST method?>
    </remark>

    <\remark>
      Downloading will typically only work if a mapping from <var|HASH> to a
      GNUnet FS URI is known, unless <var|parallel-downloads> is seet
      appropriately.
    </remark>

    <\remark>
      File URLs like <samp|file:///gnu/store/???-package-version.tar.gz> can
      be passed with return?=false and <var|upload> set appopriately to
      upload a file from the local file system at the server. The server will
      likely restrict the use of such URLs though.
    </remark>

    <paragraph|Request headers>

    <\description>
      <item*|Accept>Include <samp|application/octet-stream> when downloading
      a file

      <item*|Accept-Charset>Include UTF-8 if <samp|application/json> is
      desired.

      <item*|Content-Type><samp|application/json> for POST.
    </description>

    <paragraph|Trailing response headers>

    <\description>
      <item*|X-Rehash-Hashes>When some hashes are computed, a comma-separated
      list of the textual representation of the hashes. Eventually, hashes of
      all types <var|INPUT_HASH_TYPE> <text-dots> and <var|OUTPUT_HASH_TYPE>
      <text-dots> should be computed. Some unsolicited hashes may be computed
      as well.

      <item*|X-Rehash-Bad-URL>Value: three-digit HTTP status code, space,
      some URL. The server tried to contact this URL, but failed. In case the
      of a status code \<less\> 100:

      000 Evil: the server doesn't like this URL for its own whimsical
      reasons.

      001 No such server: name resolution trouble

      002 Connection rejected: trouble connecting to IP address (or similar)

      003 Slow: rehash found this URL to be to slow

      <\remark>
        The server should try multiple URLs, and try old URLs again later.
        (In case the server temporarily had some trouble.)
      </remark>

      <item*|X-Rehash-Spinning>Value: <samp|unfortunately>, followed by a
      space, followed by a positive number of seconds, possibly followed by a
      space and a message to be defined in the future.

      The server tried to access all URLs for the desired data, but isn't
      finding anything anymore, and downloading over GNUnet isn't progressing
      nicely. As such, it seems the network is down or the file isn't
      well-represented in GNUnet or rehash. No further data is expected
      anytime soon. The client should consider to consider the download
      failed.

      Value: <samp|no>, possibly followed by a space and a message to be
      defined in the future. The server informs that the last
      <samp|X-Rehash-Spinning: unfortunately> doesn't apply anymore.
    </description>

    <paragraph|Response headers>

    <\description>
      <item*|Content-Type>On success, <samp|application/octet-stream> if
      requested
    </description>

    <paragraph|Status codes>

    <\description>
      <item*|200 Found>(Never encountered in current implementation). (Only
      for GET)

      This has the usual meaning.

      <item*|201 Created>(Never encountered in current implementation). (Only
      for POST)

      <todo|do we really need to include Location: header? (See HTTP specs)
      Ignored for now.>

      <item*|202 Accepted>The upload / download request is accepted. Whether
      it will make reasonable progress remains to be seen.

      <item*|400 Bad Request>Some parts of the request were not understood.
      E.g., unknown hash types, unsupported URLs
    </description>

    The resource searched for always exists, even though it might never be
    found.
  </explain>
</body>

<\initial>
  <\collection>
    <associate|chapter-nr|4>
    <associate|page-first|?>
    <associate|save-aux|false>
    <associate|section-nr|0>
    <associate|subsection-nr|4>
  </collection>
</initial>