API Keys
========

APIs are accessible under the ``https://*.recras.nl/api2/apikeys`` namespace.

Currently the ``editUsers`` permission is required to access the API keys endpoint.

For security reasons, management actions are limited to requests authenticated with the ``Authorization: Basic`` method.

Retrieve a list
---------------

.. http:get:: /api2/apikeys

   Retrieve a list of API Keys

   **Request**:

   :statuscode 200: OK
   :statuscode 403: Authenticated user lacks the ``editUsers`` permission.
   :statuscode 406: Error in one of the query parameters.

   :query integer user_id: The ID value of a user account.

   **Response**:

   :json array _embedded.apikeys: The list of API keys matching the selection parameters. Each element follows the description of :http:get:`/api2/apikeys/(int:id)`.
   :json integer count: The total number of API keys in the selection
   :json object _links: Links that can be followed from this resource, according to the proposed HAL_ standard

Link relations
""""""""""""""

The following link relations may be found on the list of API keys. Note that a single relation may contain a list of links:

self, ``method: get``:
    A canonical link to this collection

self, ``method: post``:
    The location to create new collection items

next, prev, first, last:
    The resource may be paginated, this link follows the semantics as described in the `IANA link relations catalogue`_.


Retrieve a single resource
--------------------------

.. http:get:: /api2/apikeys/(int:id)

   Retrieve a single API key. **Note**: please use HAL_-links to derive the URI's for API keys instead of the ``id`` values.

   **Request**:

   :statuscode 200: OK
   :statuscode 403: Authenticated user lacks the ``editUsers`` permission.
   :statuscode 406: Error in one of the query parameters.

   **Response**:

   :json integer id: An ID value, unique for each API key 
   :json integer user_id: An ID value for the associated user account, corresponds to a staff or supplier resource.
   :json string description: A description for the API key
   :json object _links: HAL_-links relevant to this resource

Link relations
""""""""""""""

The following link relations may be found on the list of API keys. Note that a single relation may contain a list of links:

self, ``method: get``:
    A canonical link to this resource

self, ``method: put``:
    The location to update the resource. This resource follows ``PUT``-back semantics.

self, ``method: delete``:
    The location to delete the resource


Create
------

.. http:post:: /api2/apikeys

   Create a new API key. **Note**: please use the ``method: post`` link from the list resource.

   **Request**:

   :statuscode 201: Resource created
   :statuscode 406: Error in the post body

   :reqheader Content-Type: The content type for the request body. The only acceptable value is ``application/json``

   :json integer user_id: **Required.** The ID value of a user account.
   :json string description: **Required.** A description for the API key.

   **Response**:

   The response is very much like the response for :http:get:`/api2/apikeys/(int:id)`, with these extra values:

   :json string token: The value to use in the ``Authorization: Bearer`` request header. This should be treated as a secret and an opaque identifier. Please make no assumptions about its length or format. For more information and an example, see `the chapter on authentication`_.


.. _HAL: https://tools.ietf.org/html/draft-kelly-json-hal-08
.. _`IANA link relations catalogue`: https://www.iana.org/assignments/link-relations/link-relations.xhtml
.. _`the chapter on authentication`: ../authentication.html