.. index:: Documentation

.. _documentation:

Documentation requirements
==========================

Documentation URLs
------------------

Documentation base URL
^^^^^^^^^^^^^^^^^^^^^^

The documentation base URL SHOULD be the same as API's base URL but with ``/docs`` appended.

Documentation MAY live on ``http`` instead of ``https``.

Documentation URLs
^^^^^^^^^^^^^^^^^^

Documentation is RECOMMENDED to live at the following URLs (assuming `https://api.platform.com/v1/docs/` as documentation base
URL):

* Resources: ``https://api.platform.com/v1/docs/resources/{resource-name}``
* Relations: ``https://api.platform.com/v1/docs/rels/{relation-name}``

Further documentation (e.g. deprecations) should go below those. For example:

* Resource deprecation: ``https://api.platform.com/v1/docs/rels/{relation-name}/deprecation``
* Resource other: ``https://api.platform.com/v1/docs/rels/{relation-name}/{detail-subject}``
* Field deprecation: ``https://api.platform.com/v1/docs/resources/{resource-name}/{field-name}-deprecation``

Resource documentation
----------------------

Contents
^^^^^^^^

The following must be documented for each resource:

* :ref:`name <field-names>`
* description
* URL template
* supported methods
* in which resources it can be embedded
* whether ETag is supported
* whether it is deprecated
* For each linked resource:
    * :ref:`name <field-names>`
    * description
    * URL template
    * link to resource documentation
    * supported methods
    * whether it can be embedded
    * whether it is deprecated
    * whether it supports zooming
* A list of all fields with for each field:
    * :ref:`name <field-names>`
    * description
    * type value (see section [field types](#field-types))
    * format value (see section [field types](#field-types))
    * required?
    * writable?
    * modifiable?

For each deprecation the document MUST describe when the relation/resource/field will no longer be supported.

.. _field-types:

Field types
^^^^^^^^^^^

The following field types are in use (inspired by but not the same as https://developers.google.com/discovery/v1/type-format):

.. list-table::
  :widths: 30 30 60
  :header-rows: 1

  * - Type value
    - Format value
    - Meaning

  * - any
    - --
    - The field may have any type. Defined by the JSON Schema spec.

  * - array
    - --
    - A JavaScript array of values. The items field indicates the schema for the array values. Defined by the JSON Schema spec.

  * - boolean
    - --
    - A boolean value, either "true" or "false". Defined by the JSON Schema spec.

  * - integer
    - int32
    - A 32-bit signed integer. It has a minimum value of -2,147,483,648 and a maximum value of 2,147,483,647 (inclusive).

  * - integer
    - uint32
    - A 32-bit unsigned integer. It has a minimum value of 0 and a maximum value of 4,294,967,295 (inclusive).

  * - number
    - double
    - A double-precision 64-bit IEEE 754 floating point.

  * - number
    - float
    - A single-precision 32-bit IEEE 754 floating point.

  * - object
    - --
    - A JavaScript object. Defined by the JSON Schema spec.

  * - string
    - --
    - An arbitrary string. Defined by the JSON Schema spec.

  * - string
    - byte
    - A padded, base64-encoded string of bytes, encoded with a URL and filename safe alphabet (sometimes referred to as "web-safe" or "base64url"). Defined by RFC4648.

  * - string
    - date
    - An ISO8601 date in the format ``YYYY-MM-DD``. Defined in the JSON Schema spec.

  * - string
    - date-time
    - An ISO8601 timestamp in UTC time. This is formatted as ``YYYY-MM-DDThh:mm:ss.fffZ``.

  * - string
    - int64
    - A 64-bit signed integer. It has a minimum value of -9,223,372,036,854,775,808 and a maximum value of 9,223,372,036,854,775,807 (inclusive).

  * - string
    - uint64
    - A 64-bit unsigned integer. It has a minimum value of 0 and a maximum value of (2^64)-1 (inclusive).


Document link relations
-----------------------

Getting started guide
---------------------

API reference
-------------

Example code
------------


TODO
----

* Integrate: