.. _micro.rest.api:

Serving REST APIs
=================

.. highlight:: python

.. currentmodule:: micro.rest.api

.. note::

   This topic describes how to create a simple REST API server with built-in Swagger support.
   For REST


Shortcut for creating API`s
---------------------------

.. autofunction:: make_api


.. _micro.rest.api_system_routes:

Pre-created system routes
-------------------------
Any API server created with ``make_api()`` will have next routes serving the content:

- /swagger.json - serving the Swagger API description JSON object (see `Swagger specification`_)
- /health-check - serving the two bytes 'UP', which is suitable for checking that API server is up and running

API servers which are running in debug mode (see `micro.rest.api_debug_mode`_) will have the next routes pre-defined:

- /_debug - which serves the redirect into Swagger UI interface
- /_debug/ - under this prefix we serve Swagger UI interface static files. We have a pretty convenient `swagger` task in
    our Rakefile for cloning Swagger UI distribution into the right place for serving its static.

.. _micro.rest.api_debug_mode:

Running API server in development for debugging purposes
--------------------------------------------------------

The following code runs an API server without any declared endpoints in debug mode.

 .. code-block:: python

    from micro.core import Micro

    from micro.rest import make_api

    app = Micro()

    api_instance = make_api(app, name='Micro.Rest example server',
        description='An example API server without any endpoints', version='1')
    api_instance.debug(host='0.0.0.0', port=8080, name='TestAPI')


This runs API server listening on 0.0.0.0:8080 with log prefix 'TestAPI'


.. _micro.rest.api_running_in_production:

Running API server in production
--------------------------------

The class micro.rest.api.API (and its subclasses which are created on fly with ``make_api()`` method) are full
compatible with `aiohttp gunicorn worker`_


.. _aiohttp gunicorn worker: https://github.com/KeepSafe/aiohttp/blob/v0.15.3/docs/gunicorn.rst
.. _Swagger specification: https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md