Metadata-Version: 2.1
Name: api_compose
Version: 0.0.8
Summary: A Framework for orchestrating, asserting and reporting on API calls with templates
Author: Ken
Author-email: kenho811job@gmail.com
License: Apache License 2.0
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.9
Description-Content-Type: text/x-rst
Provides-Extra: test
Provides-Extra: dist
License-File: LICENSE.txt

API Compose
~~~~~~~~~~~~~~~~~~~~

Installation
============================

`PyPI Package <https://pypi.org/project/api-compose>`_

.. code-block::

   pip install api-compose

Get Started
============================

.. code-block::

   # creates a sample project for you to build on
   acp scaffold <your_project_name>

Run the programme
============================

.. code-block::

   acp run

- Explore the CLI's capabilities by running `acp` or `acp --help`


Examples
============================

- Examples are in **./examples** folder

`Bullish API <./examples/bullish>`_

`Cat API <./examples/cat_api>`_

Features
=====================

Declaration-based API Call Composition
--------------------------------------------------

- Allows API calls to be declared as Models.

- Distinguishes between **Compile Time Rendering** and **Run Time Rendering**

- Leverages networkx to determine the execution order of each API call.

- Exposes decorator **@JinjaGlobalRegistry** to for users to create jinja globals for rendering.

- (Comimg soon) Auto-retry Scenario if not all Actions are in ENDED state.


Useful Builtin Jinja Globals
>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>

Builtin Jinja Globals allow users to specify which part (e.g. headers, body etc.) of an API action (e.g. login, get_images etc.) to use.

.. code-block::

    ## Get the value of the field field_one of the returned body from the login_action API call
    {{ output_body('login_action', '$.field_one') }}

    ## Get the value of the field field_one of the input headers from the login_action API call
    {{ input_headers('login_action', '$.field_one') }}

    ## Get the rendered body of the current API call
    {{ config_body('self') }}

Supported API Calls Type - Adapters
>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>

- Below is the table which breaks down the type of API Call by

    - Protocol (Column)
    - Data Format (Row)


.. table::

    +------+------+-----------+-----+
    |      | HTTP | WebSocket | FIX |
    +======+======+===========+=====+
    | json | True | TBD       | TBD |
    +------+------+-----------+-----+
    | xml  | WIP  | TBD       | TBD |
    +------+------+-----------+-----+

- WIP means Working in Progress. It means it is being worked on now.

- TBD means to be determined.  It means it will be planned in the future.


Schema Validation
---------------------------
- Leverages **jsonschema** and **xmlschema** to validate returned json and xml data respectively.

Assertion
---------------------------

- Allows users to use Jinja to make assertions between API Calls Result

.. code-block::

    # assert that two different fields in two different actions have the same value
    {{ output_body('action_one', $.field_one) == output_body('action_two', '$.field_two') }}


Reporting
---------------------------

- Presents Test Results nicely in HTML reports



Architectural Diagram
===========================

.. figure:: ./diagrams/framework_architecture.png
   :scale: 70%
   :align: center
   :alt: API Testing Framwork Architecture

   The above is the  API Testing Framwork Architecture.

   Lucid Chart here: `https://lucid.app/lucidchart/f8d1f9f9-bc93-46ec-8e4f-6561a4c822c3/edit?beaconFlowId=70D4EDD3B7971E6C&invitationId=inv_c7b45baf-050c-480b-923e-2979440ce4c8&page=0_0#`


.. figure:: ./diagrams/framework_building_blocks.png

    Hierarchical structure of the models

    Lucid Chart here: https://lucid.app/lucidchart/f8d1f9f9-bc93-46ec-8e4f-6561a4c822c3/edit?beaconFlowId=70D4EDD3B7971E6C&invitationId=inv_c7b45baf-050c-480b-923e-2979440ce4c8&page=p0OVapsRWlkY#



Jinja Templating
============================

Compile Time Rendering
--------------------------------

- To make templates reusable, the programme exposes the means to render template files using the below syntax:

.. code-block::

    block_start_string='[%'
    block_end_string='%]'
    variable_start_string='[['
    variable_end_string=']]'
    comment_start_string='[#'
    comment_end_string='#]'

Run Time Rendering
--------------------------------

- To allow for inter-API Call dependencies within a given scenario, the programme also exposes the means to render templated fields using the below syntax:

.. code-block::

    block_start_string='{%'
    block_end_string='%}'
    variable_start_string='{{'
    variable_end_string='}}'
    comment_start_string='{#'
    comment_end_string='#}'




Config File
============================

File name is `config.yaml`

.. code-block::

    # Generate config.yaml
    acp cfg init
