.. _usage:
.. include:: references.rst

========
Usage
========

Package
~~~~~~~

To use `Magpie` in a project, first you need to install it. To do so, you can do a basic ``pip install``.
For more details or other installation variants and environment preparation, see `installation`_ and
`configuration`_ procedures.

After this, you should be able to import the Python package to validate it is installed properly using::

    import magpie


Web Application
~~~~~~~~~~~~~~~~~~~~~

In most situation, you will want to run `Magpie` as a Web Application in combination with some Web Proxy
(e.g.: `Twitcher`_) that can interrogate `Magpie` about applicable user authentication and permission authorization
from the HTTP request session. To start the application, you can simply run the following command::

    make start

This will first install any missing dependencies in the current environment (see `installation`_), and will after start
a basic Web Application on ``localhost:2001`` with default configurations. Please note that you **MUST** have a
`PostgreSQL`_ database connection configured prior to running `Magpie` for it to operate (refer to `Configuration`_
for details).

For running the application, multiple
`WSGI HTTP Servers` can be employed (e.g.: `Gunicorn`_, `Waitress`_, etc.). They usually all support as input an INI
configuration file for specific settings. `Magpie` also employs such INI file to customize its behaviour.
See `Configuration`_ for further details, and please refer to the employed `WSGI` application documentation of your
liking for their respective setup requirements.


API
~~~~~~~

When the application is started, the Swagger API should be available under ``/api`` path. This will render the *current*
version API and applicable requests. Please refer to this documentation to discover all provided API paths and
operations supported by `Magpie` on a *running* instance (that could be older than latest code base). Alternatively,
documentation of *all* versions is available on `ReadTheDocs`_.

The API allows an administrator-level user to modify services, resources, users and groups references via HTTP requests.
To do these kind of operations, sufficient access rights must be provided to the corresponding user (either directly or
through administrative-level group membership).

Some API routes are accessible by *any*-level user access. These are designated by :term:`Logged User` in the
documentation. When accessing such API paths, the applicable user for which the request is accomplished uses contextual
information from authentication headers and/or cookies of the request. When no user is authenticated, a minimal subset
of paths will provide some publicly available details, such as current session user. Other routes will be more verbose
according to the applicable user permission (or is inherited group memberships).

.. versionchanged:: 2.0.0

    As of this version, some API paths will offer additional :term:`Logged User` operations such as self-registration
    to publicly available groups. See the appropriate API version documentation for routes that could be added or
    adjusted with this new functionality. Note also that a valid user account will still be required to access these
    routes.

Please refer to :ref:`permissions` for further details about applicable user access levels.

CLI
~~~~~~~

After successful `installation`_ of `Magpie` package, multiple `helper utilities <utilities>`_ become available
as CLI applications callable from the shell. These can be quite useful to run typical `Magpie` operations targeting
a local or remote instance. Please refer to the relevant page for further details.

GUI
~~~~~~~

When the application is started, `Magpie`'s UI should be directly accessible on the top endpoint path. This interface
allows quicker editing of elements accessible through the API by providing common operations such as modifying service
fields or adjusting specific user-resource permissions. To have access to this interface, the user must have
administrator permissions.

.. versionchanged:: 2.0.0

    User-scoped views such as logged-user account details are now accessible to non-administrator level users.
    These offer some basic functionalities such as registration to publicly visible groups. Users minimally require
    to be logged-in (successful :term:`Authentication`) in order to access these pages. The UI pages are accessible
    using the ``Account`` button from the main entrypoint of the `Magpie` UI.

Additional Utilities
~~~~~~~~~~~~~~~~~~~~

Multiple `utilities`_ are provided either directly within `Magpie` as a package or through external resources.
Please refer to this section for more details.

.. _configuration: configuration.rst
.. _installation: installation.rst
.. _permissions: permissions.rst
.. _utilities: utilities.rst