Access Request
==============

A :class:`AccessRequest` object represents the access request generated by :ref:`PEP <abac_pep>` in the
:ref:`ABAC architecture <abac_arch>`. All you need to do is take any kind of incoming user request
(REST request, SOAP, etc.) and build an :class:`AccessRequest` object out of it as shown below:

.. code-block:: python

   from py_abac import AccessRequest
   from flask import request, session

   # Create a access request JSON from flask request object
   request_json = {
       "subject": {
           "id": "",
           "attributes": {"name": request.values.get("username")}
       },
       "resource": {
           "id": "",
           "attributes": {"name": request.path}
       },
       "action": {
           "id": "",
           "attributes": {"method": request.method}
       },
       "context": {}
   }
   # Parse JSON and create access request object
   request = AccessRequest.from_json(request_json)


You might have noticed the presence of empty  :code:`"id"` fields for the :code:`subject` , :code:`resource` and
:code:`action` access control elements in the above example. These are called **target IDs** and are mandatory fields
for creating an access request object in Py-ABAC. The purpose of these fields is explained in detail in the
:ref:`targets_block` subsection of Policy Language. If you are unsure of their usage, you can safely set them to an
empty string.

.. note::

   Target IDs are used by :ref:`Storage <components_storage>` for efficient policy retrieval. If you don't set them in any
   polices, a default value of "*" is used which results in the storage returning all stored polices for evaluation to PDP.
   Thus even though targets are not mandatory, it is a encouraged to have them in systems with large number of policies.

.. note::

   For backward compatibility with Py-ABAC v0.2.0 you can also use the :class:`Request` class to create access request.
