Skip to content

Commit

Permalink
feat: add tables for api params, fix image alt text
Browse files Browse the repository at this point in the history
  • Loading branch information
@howhelan
howhelan committed Jul 29, 2021
1 parent ce4e37d commit 6f0fdd8
Show file tree
Hide file tree
Showing 3 changed files with 219 additions and 122 deletions.
300 changes: 189 additions & 111 deletions source/client.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,165 +19,243 @@ API

``GET /data/<path>``
^^^^^^^^^^^^^^^^^^^^


An unsecure request to the client for data at a given path. The response is not the data itself, but an HTML document with an iframe which makes a secure request to retrieve the data.

Path Parameters
~~~~~~~~~~~~~~~

* ``<path>`` is a jsonpath-style string prepended and appended by a period,
e.g.

* ``.someKey.``
* ``.someObj.someVal.``
* ``.someArr[0].``
.. list-table::
:widths: 20 15 45 20
:header-rows: 1

* - Parameter
- Required?
- Description
- Example
* - ``path``
- Required
- A jsonpath-style string prepended and appended by a period which represents the path of the data
- ``.someObj.someVal.``

Query Parameters
~~~~~~~~~~~~~~~~

* ``css`` (optional) is a URL-encoded CSS block meant to style the displayed data.

* The HTML to style can be found `here`_.

* ``edit`` (optional) is a boolean indicating whether the data will be displayed in an
editable form field.

* ``true``: The value will be displayed in a submittable input box
appropriate for its data type.
* ``false``: The value will simply be displayed as a string.
* Default: ``false``

* ``data_type`` (required) specifies the type of data to expect; this is particularly
useful when creating new data that does not yet have a type. The value can be
one of:

* ``Bool``
* ``U64``
* ``I64``
* ``F64``
* ``String``

* ``relay_url`` (optional) is the URL endpoint which will receive a ``POST``
HTTP request upon submission of editable data.

* This would typically be a URL controlled by the host of the Redact-enabled
website and used for internal bookkeeping.
.. list-table::
:widths: 10 15 45 10 30
:header-rows: 1

* - Parameter
- Required?
- Description
- Default
- Example
* - ``css``
- Optional
- A URL-encoded CSS block meant to style the displayed data. The HTML to style can be found `here`_.
-
- ``iframe%7Bborder%3Anone%3B%7D``
* - ``edit``
- Optional
- A boolean indicating whether the data will be displayed in an editable form field. If ``true``, the value will be displayed in a submittable input box appropriate for its data type.
- ``false``
- ``true``
* - ``data_type``
- Required
- specifies the type of data to expect; this is particularly useful when creating new data that does not yet have a type. The value can be one of:

* ``Bool``
* ``U64``
* ``I64``
* ``F64``
* ``String``
-
- ``String``
* - ``relay_url``
- Optional
- the URL endpoint to which a ``POST`` HTTP request will be sent upon submission of editable data. This would typically be a URL controlled by the host of the Redact-enabled website and used for internal bookkeeping.
-
- ``https://foo.com/redact/relay``

.. _here: https://github.com/pauwels-labs/redact-client/tree/main/static/secure.handlebars

``GET /data/<path>/<token>``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^


An secure request to the client for data at a given path. The response is and HTML document displaying the contents of the data.

Header Parameters
~~~~~~~~~~~~~~~~~

* ``Cookie sid=<session ID>``
.. list-table::
:widths: 20 20 60
:header-rows: 1

* The session ID is used internally by the :ref:`Client<client>` to associate the request
with a session in its session store
* - Header Name
- Required?
- Description
* - ``Cookie sid``
- Required
- The session ID is used internally by the :ref:`Client<client>` to associate the request with a session in its session store.

Path Parameters
~~~~~~~~~~~~~~~

* ``<path>`` is a jsonpath-style string prepended and appended by a period,
e.g.

* ``.someKey.``
* ``.someObj.someVal.``
* ``.someArr[0].``
.. list-table::
:widths: 20 15 45 20
:header-rows: 1

* - Parameter
- Required?
- Description
- Example
* - ``path``
- Required
- A jsonpath-style string prepended and appended by a period which represents the path of the data
- ``.someObj.someVal.``
* - ``token``
- Required
- A random, 256-bit, upper-case alphanumeric CSRF token that is generated and used internally by the :ref:`Client<client>`
-

* ``<token>`` is a random, 256-bit, upper-case alphanumeric CSRF token that is
generated and used internally by the :ref:`Client<client>`

Query Parameters
~~~~~~~~~~~~~~~~

.. note:: These query parameters are identical to those of ``GET /data/<path>``
and are typically automatically included in this request by the :ref:`Client<client>`.

* ``css`` (optional) is a URL-encoded CSS block meant to style the displayed data.

* The HTML to style can be found `here`_.

* ``edit`` (optional) is a boolean indicating whether the data will be displayed in an
editable form field.

* ``true``: The value will be displayed in a submittable input box
appropriate for its data type.
* ``false``: The value will simply be displayed as a string.
* Default: ``false``

* ``data_type`` (required) specifies the type of data to expect; this is particularly
useful when creating new data that does not yet have a type. The value can be
one of:

* ``Bool``
* ``U64``
* ``I64``
* ``F64``
* ``String``

* ``relay_url`` (optional) is the URL endpoint which will receive a ``POST``
HTTP request upon submission of editable data.

* This would typically be a URL controlled by the host of the Redact-enabled
website and used for internal bookkeeping.
.. list-table::
:widths: 10 15 45 10 30
:header-rows: 1

* - Parameter
- Required?
- Description
- Default
- Example
* - ``css``
- Optional
- A URL-encoded CSS block meant to style the displayed data. The HTML to style can be found `here`_.
-
- ``iframe%7Bborder%3Anone%3B%7D``
* - ``edit``
- Optional
- A boolean indicating whether the data will be displayed in an editable form field. If ``true``, the value will be displayed in a submittable input box appropriate for its data type.
- ``false``
- ``true``
* - ``data_type``
- Required
- specifies the type of data to expect; this is particularly useful when creating new data that does not yet have a type. The value can be one of:

* ``Bool``
* ``U64``
* ``I64``
* ``F64``
* ``String``
-
- ``String``
* - ``relay_url``
- Optional
- the URL endpoint to which a ``POST`` HTTP request will be sent upon submission of editable data. This would typically be a URL controlled by the host of the Redact-enabled website and used for internal bookkeeping.
-
- ``https://foo.com/redact/relay``

.. _here: https://github.com/pauwels-labs/redact-client/tree/main/static/secure.handlebars

``POST /data/<token>``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

A secure request to the client to update existing data or create new data at a given path.

Header Parameters
~~~~~~~~~~~~~~~~~

* ``Content-Type application/x-www-form-urlencoded``

* ``Cookie sid=<session ID>``
.. list-table::
:widths: 20 20 60
:header-rows: 1

* The session ID is used internally by the :ref:`Client<client>` to associate the request
with a session in its session store
* - Header Name
- Required?
- Description
* - ``Cookie sid``
- Required
- The session ID is used internally by the :ref:`Client<client>` to associate the request with a session in its session store.
* - ``Content-Type``
- Required
- Must be: ``x-www-form-urlencoded``

Path Parameters
~~~~~~~~~~~~~~~

* ``<token>`` is a random, 256-bit, upper-case alphanumeric CSRF token that is
generated and used internally by the :ref:`Client<client>`.
.. list-table::
:widths: 20 15 45 20
:header-rows: 1

* - Parameter
- Required?
- Description
- Example
* - ``token``
- Required
- A random, 256-bit, upper-case alphanumeric CSRF token that is generated and used internally by the :ref:`Client<client>`
-

Query Parameters
~~~~~~~~~~~~~~~~

* ``css`` (optional) is a URL-encoded CSS block meant to style the displayed data.

* The HTML to style can be found `here`_

* ``edit`` (optional) is a boolean indicating whether the data will be displayed in an
editable form field.

* ``true``: The value will be displayed in a submittable input box
appropriate for its data type.
* ``false``: The value will simply be displayed as a string.
* Default: ``false``
.. list-table::
:widths: 10 15 45 10 30
:header-rows: 1

* - Parameter
- Required?
- Description
- Default
- Example
* - ``css``
- Optional
- A URL-encoded CSS block meant to style the displayed data. The HTML to style can be found `here`_.
-
- ``iframe%7Bborder%3Anone%3B%7D``
* - ``edit``
- Optional
- A boolean indicating whether the data will be displayed in an editable form field. If ``true``, the value will be displayed in a submittable input box appropriate for its data type.
- ``false``
- ``true``

Body Parameters
~~~~~~~~~~~~~~~

* ``<path>`` (required) is a jsonpath-style string prepended and appended by a period,
e.g.

* ``.someKey.``
* ``.someObj.someVal.``
* ``.someArr[0].``
.. list-table::
:widths: 10 15 45 30
:header-rows: 1

* - Parameter
- Required?
- Description
- Example
* - ``path``
- Required
- a jsonpath-style string prepended and appended by a period
- ``.someObj.someVal.``
* - ``value``
- Required
- The value of the data being submitted
- ``String``
* - ``value_type``
- Required
- Specifies the type of data to expect; this is particularly useful when creating new data that does not yet have a type. The value can be one of:

* ``Bool``
* ``U64``
* ``I64``
* ``F64``
* ``String``
- ``String``
* - ``relay_url``
- Optional
- the URL endpoint to which a ``POST`` HTTP request will be sent upon submission of editable data. This would typically be a URL controlled by the host of the Redact-enabled website and used for internal bookkeeping.
- ``https://foo.com/redact/relay``

* ``value`` (required) is the actual value of the data being submitted

* ``value_type`` (required) specifies the type of data to expect; this is particularly
useful when creating new data that does not yet have a type. The value can be
one of:

* ``Bool``
* ``U64``
* ``I64``
* ``F64``
* ``String``
.. _here: https://github.com/pauwels-labs/redact-client/tree/main/static/secure.handlebars

* ``relay_url`` (optional) is the URL endpoint which will receive a ``POST``
HTTP request upon submission of editable data.
6 changes: 3 additions & 3 deletions source/overview.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -53,7 +53,7 @@ The general flow to request data to be displayed works as such:
There are additional parameters that can be provided which further customize
the :ref:`Client<client>`'s response, but are left out here for simplicity.

.. image:: _static/images/iframe_1.png
.. image:: _static/images/iframe_1.png
:alt: Web page body, with the iframe reference to a Redact path

2. The :ref:`Client<client>` receives the request and does four things:
Expand All @@ -68,7 +68,7 @@ The general flow to request data to be displayed works as such:

<iframe src="/data/.profile.firstName./498DF68A39A51DE648799EE13CD26D2163863FC5F43814B8895B78BBA45935A0"></iframe>

.. image:: _static/images/iframe_2.png
.. image:: _static/images/iframe_2.png
:alt: Web page body after first iframe is rendered, with inner iframe referencing the Redact path and session token

3. Upon rendering the iframe response, the browser makes another request to the
Expand All @@ -84,7 +84,7 @@ The general flow to request data to be displayed works as such:
decrypting it, and responding with an HTML page containing the
plaintext. If the tokens do not match, the request is rejected.

.. image:: _static/images/iframe_3.png
.. image:: _static/images/iframe_3.png
:alt: Web page body after secure iframe is rendered, with the decrypted Redact data

This process allows the :ref:`Client<client>` to ensure that the only time it responds
Expand Down

0 comments on commit 6f0fdd8

Please sign in to comment.