======
People
======

Add, remove, or update the entry for a given person.

GET
===

DESCRIPTION
    Retrieve information on a given person.

URL STRUCTURE
    .. code-block:: guess

        https://www.example.com/<version>/people/<name>

    :version: API version.
    :name: Name of the person

VERSIONS
    v1

ERRORS
    :404: No user of that name

EXAMPLES
    * `GET unknown person`_
    * `PUT then GET`_
    * `Redirect to documentation`_

PUT
===

DESCRIPTION
    Create a new person. Also overwrites an existing person of that name.

URL STRUCTURE

    .. code-block:: guess

        https://www.example.com/<version>/people/<name>

    :version: API version.
    :name: Name of the person

VERSIONS
    v1

ERRORS
    | 200 - Ok
    | 404 - No user of that name

EXAMPLE
    * `PUT then GET`_


PATCH
=====

DESCRIPTION
    Update a new person.

URL STRUCTURE

    .. code-block:: guess

        https://www.example.com/<version>/people/<name>

    :version: API version.
    :name: Name of the person

VERSIONS
    v1

ERRORS
    | 200 - Ok
    | 404 - No user of that name

EXAMPLE
    * `PATCH then GET`_


DELETE
======

DESCRIPTION
    Delete the entry for a specific person.

URL STRUCTURE
    .. code-block:: guess

        https://www.example.com/<version>/people/<name>

    :version: API version.
    :name: Name of the person

VERSIONS
    v1

ERRORS
    :404: No user of that name

EXAMPLE
    * `DELETE person`_

DELETE (all people)
===================

DESCRIPTION
    Delete entries for everyone.

URL STRUCTURE
    .. code-block:: guess

        https://www.example.com/<version>/people

    :version: API version.

VERSIONS
    v1

ERRORS
    (none)

EXAMPLE
    * `DELETE all`_


Examples
========

GET unknown person
~~~~~~~~~~~~~~~~~~

    .. command-output:: http --pretty all -jv GET localhost:5000/v1/people/nobody

PUT then GET
~~~~~~~~~~~~

    .. command-output:: http --pretty all -jv PUT localhost:5000/v1/people/tim email="a@b.c"; echo "\n"; http --pretty all -jv GET localhost:5000/v1/people/tim
        :shell:

PATCH then GET
~~~~~~~~~~~~~~

    .. command-output:: http --pretty all -jv PATCH localhost:5000/v1/people/tim comment="hello world"; echo "\n"; http --pretty all -jv GET localhost:5000/v1/people/tim
        :shell:

DELETE person
~~~~~~~~~~~~~

Note that the second DELETE fails.

    .. command-output:: http --pretty all -jv DELETE localhost:5000/v1/people/tim; echo "\n"; http --pretty all -jv DELETE localhost:5000/v1/people/tim
        :shell:

DELETE all
~~~~~~~~~~

    .. command-output:: http --pretty all -jv DELETE localhost:5000/v1/people

Redirect to documentation
~~~~~~~~~~~~~~~~~~~~~~~~~

A GET with an HTTP Accept Header preferring HTML over JSON will redirect to the
on-line documentation.

    .. command-output:: http --pretty all -v GET localhost:5000/v1/people
