===
API
===
To improve work and communication with Scrooge, we have prepared api. Currently, there is only push api which can be used to push usages data by services. In the future, we are planning to create pull api for generating report data only for a single venture/service. To communicate with API, use JSON as a message format and REST API for maintenance of communication standards.


Push API
~~~~~~~~

.. image:: images/push_api.png

-------------------
General description
-------------------

Every service can upload data to Scrooge with the use of its resources
(e.g. requests count, transfer, etc.) by ventures. To upload data to Scrooge, some preconditions must be satisfied:

* usage type(s) used by service must be added to Scrooge
* service has to be added to Scrooge
* usage type(s) must be connected with the service

A unique symbol has to be provided for every service in Scrooge, which is later used to identify the service through API. Venture and usage type(s) are also identified using these symbols

The unit of resource usage doesn't matter (e.g. in the case of transferring kB, MB, GB) - the most important thing is to keep the unit of every usage the same
(even abstract) – after all, the cost of service is distributed to ventures proportionally to their usages (of resources).

If a service has more than one usage type, it is necessary to provide their percentage division in the period of time (e.g. transfer – 30%, requests count
– 70%, which means that 30% of the total cost of service is distributed proportionally to the transfer usage and 70% proportionally to the requests count).


-------------------------
User Guide (step-by-step)
-------------------------
.. _user-api-label:

1. (General) Ralph Admin part

  a. Create a user or use the account that is already provided for your service.
  b. Log in to Ralph using technical user credentials and find out what your API Key is (RALPH_URL/user/preferences/api_key)

2. Scrooge Admin part

  a. Create Usage Type(s) (one or more) that reflect(s) resources used by service (RALPH_URL/admin/ralph_pricing/usagetype/add/). Every service usage type must have a unique symbol.

    * Leave "Show usage type in report" checked.
    * Type: select "Service usage type".

  b. Create Service (RALPH_URL/admin/ralph_pricing/service/add/). Every service must have a unique symbol that will be used later to identify the service in the API message. Possible options for service:


    * Base usage types – base usage types that will be used to calculate the cost of service (if you don't know what to select, select all).
    * Dependency –this field is used to select dependent services (a part of dependent service cost (cost of dependent service that is generated by current service ventures) will be included in the total service cost)
    * Use universal plugin – if your service does not have a dedicated plugin, keep this option checked.
    * Ventures – ventures that provide a service (ventures with physical or virtual machines that are used by the service)
    * Service usage types – here, you have to select usage types created in the previous step. Notice that only usage types with the “Service usage type” are presented here. If you only have one usage type for your service, select it and type 100 inits percentage field.


3. API usage part

  Send a JSON message to API endpoint (RALPH_URL/scrooge/api/v0.9/serviceusages/) with data in the format described in the “Technical description” section.


.. _technical-label:

---------------------
Technical description
---------------------

""""""""""""""
API definition
""""""""""""""
::

  {
    "service": "<service_symbol>",
    "date": "<date>",
    "overwrite": "<delete_all_previous|values_only|no>",
    "venture_usages": [
      {
        "venture": "<venture_symbol>",
        "usages": [
          {
            "symbol": "<usage_type_1_symbol>",
            "value": <usage1>
          },
          ...
        ]
      },
      ...
    ]
  }


Example::

  {
    "service": "service_symbol",
    "date": "2111-11-11",
    "overwrite": "delete_all_previous",
    "venture_usages": [
      {
        "venture": "venture1",
        "usages": [
          {
            "symbol": "requests",
            "value": 123
          },
          {
            "symbol": "transfer",
            "value": 321
          }
        ]
      },
      {
        "venture": "venture2",
        "usages": [
          {
            "symbol": "requests",
            "value": 543
          },
          {
            "symbol": "transfer",
            "value": 565
          }
        ]
      },
      {
        "venture": "venture3",
        "usages": [
          {
            "symbol": "requests",
            "value": 788
          },
          {
            "symbol": "transfer",
            "value": 234
          }
        ]
      }
    ]
  }

"""""""""""""
Communication
"""""""""""""

Communication with Scrooge API takes place using the HTTP protocol. Data should be sent with the POST request. Authentication is done using HTTP header "Authorization: ApiKey <username>:<api_key>", where api_key is a key generated to a user in Ralph (see *Ralph Admin part*).

"""""""""""""""""""""""""""
Overwriting previous values
"""""""""""""""""""""""""""

API provides a way to define how to treat previous service usages values uploaded for a given date (e.g. when data is sent twice for a given date). The possible actions (overwrite) is:

* ``delete_all_previous`` - all previous usages for a given date are removed before inserting new data

* ``values_only`` - previously uploaded usages are overwritten by new values

* ``no`` - any usage is removed - new usages are appended to the old ones

Example: first data package is (A:1, B:2), the next one is (B:3, C:4) - final data will be as follows:

* ``delete_all_previous`` - (B:3, C:4)
* ``values_only`` (default) - (A:1, B:3, C:4)
* ``no`` - (A:1, B:2, B:3, C:4) (cumulatively: B:5)

Default action (when overwrite is not passed) is `no`.

"""""""""""""""""""""""""""""""
Possible responses (HTTP codes)
"""""""""""""""""""""""""""""""

201 - everything ok, data saved properly.

400 - invalid symbol (venture, usage type or service).

401 - authorization/authentication error.

500 - error on server side during data processing.


Pull API
~~~~~~~~

Coming soon...
