134 lines
5.1 KiB
ReStructuredText
134 lines
5.1 KiB
ReStructuredText
.. include:: aliases.rst
|
|
|
|
.. _api:
|
|
|
|
===
|
|
API
|
|
===
|
|
|
|
The design document for the API can be found below. This document contains
|
|
the API as of the current release::
|
|
|
|
https://docs.google.com/document/d/14hM7-GSm3CcyohPT2Q7GalyrQRohVcx77hxEx4AO4Bk/edit#
|
|
|
|
There are two top-level concepts in today's API: Policies and Data-sources.
|
|
|
|
* Policies have *rules* that describe the permitted states of the cloud,
|
|
along with *tables* representing abstractions of the cloud state.
|
|
* Data-sources have *tables* representing the current state of the cloud.
|
|
* The *tables* of both policies and data-sources have rows that describe
|
|
their contents.
|
|
|
|
|
|
1. Policy (/)
|
|
=============
|
|
|
|
There is currently exactly 1 policy provided by the system, called
|
|
*classification*. Eventually we will support the creation/deletion of policies
|
|
to enable multitenancy.
|
|
|
|
|
|
======= ============================ ================================
|
|
Op URL Result
|
|
======= ============================ ================================
|
|
GET .../policies List policies
|
|
GET .../policies/<policy-id> Read policy properties
|
|
======= ============================ ================================
|
|
|
|
|
|
2. Policy Rules (/policies/<policy-id>/...)
|
|
===========================================
|
|
|
|
Each policy is a collection of rules. Congress supports the usual CRUD
|
|
operations for changing that collection. Eventually a rule will have
|
|
meta-properties like *comments*, but for now the only field a
|
|
rule contains is *rule*, which is a string containing a single statement
|
|
from the policy language described in :ref:`policy`.
|
|
|
|
======= ======================= ======================
|
|
Op URL Result
|
|
======= ======================= ======================
|
|
GET .../rules List policy rules
|
|
POST .../rules Create policy rule
|
|
GET .../rules/<rule-id> Read policy rule
|
|
DELETE .../rules/<rule-id> Delete policy rule
|
|
======= ======================= ======================
|
|
|
|
|
|
3. Policy Tables (/policies/<policy-id>/...)
|
|
============================================
|
|
|
|
All the tables mentioned in the rules of a policy can be queried
|
|
via the API.
|
|
|
|
======= ========================== =========================
|
|
Op URL Result
|
|
======= ========================== =========================
|
|
GET .../tables List tables
|
|
GET .../tables/<table-id> Read table properties
|
|
======= ========================== =========================
|
|
|
|
|
|
4. Policy Table Rows (/policies/<policy-id>/tables/<table-id>/...)
|
|
==================================================================
|
|
|
|
Rules are used to instruct Congress how to create new tables from existing
|
|
tables. Congress allows you to query the actual contents of tables
|
|
at any point in time. Congress will also provide a trace of how
|
|
it computed a table, to help policy authors understand why
|
|
certain rows belong to the table and others do not.
|
|
|
|
======= ====================== =====================================================
|
|
Op URL Result
|
|
======= ====================== =====================================================
|
|
GET .../rows List rows
|
|
GET .../rows?trace=true List rows with explanation (use 'printf' to display)
|
|
======= ====================== =====================================================
|
|
|
|
|
|
5. Data sources (/)
|
|
===================
|
|
|
|
Data sources (e.g. Nova/Neutron) can be queried via the API. Each data source
|
|
is effectively a collection of tables.
|
|
|
|
======= ================================ ======================================
|
|
Op URL Result
|
|
======= ================================ ======================================
|
|
GET .../data-sources List data sources
|
|
GET .../data-sources/<ds-id> Read data source properties
|
|
======= ================================ ======================================
|
|
|
|
|
|
6. Data source Tables (/data-sources/<ds-id>/...)
|
|
=================================================
|
|
|
|
Each data source maintains a collection of tables (very similar to a Policy).
|
|
The list of available tables for each data source is available via the API.
|
|
|
|
======= ========================== =========================================
|
|
Op URL Result
|
|
======= ========================== =========================================
|
|
GET .../tables List data sources
|
|
GET .../tables/<table-id> Read data source properties
|
|
======= ========================== =========================================
|
|
|
|
|
|
7. Data source Table Rows (/data-sources/<ds-id>/tables/<table-id/...)
|
|
======================================================================
|
|
|
|
The contents of each data source table (the rows of each table) can be queried
|
|
via the API as well.
|
|
|
|
======= ========================== =================================
|
|
Op URL Result
|
|
======= ========================== =================================
|
|
GET .../rows List rows
|
|
======= ========================== =================================
|
|
|
|
|
|
|
|
|
|
|
|
|