[Agora-System](/sqedw7tHRye1RoAt5O108A) --- [API](/TreDITwVTiK_KRemt9QOLA) --- [Message Sequences](/AUbhB5KxSb2jQJBloKtC1g) --- [Asset (Proposal)](/cICGuug-Tde1sGuvpsBAJQ) --- [PoC Definition](/aSqmHZ4uRW-iC9N_Pesd5g) --- [Old Stuff](/B4Nn8Zn9RVyGJDk4bHYHbw) --- [Demo](/rAv27FvBQXmv_rLpKQB25w)

# AGORA PoC v0.2 | API

[toc]

## API Versioning

At some point, there should exist an APi Version based on the path structure (`/v1/keeper` …).

:::info
*All Components*
:::

:::warning
all comonents should advertise themselves honestly e.g. via User-Agent-Headers
:::

**API**

*incoming*

| method | path | description | comment |
| ------ | ----- | --------------- | ------- |
| GET | /cert | get Certificate | :white_circle: |
| GET | /parents | Get Components at Level $n-1$ | :x: |
| POST | /register | receive registrations of Components in Level $n+1$ | :recycle:
| POST | /unregister | receive deregistrations of Components from Level $n+1$ | :x:
| GET | /type | get component type | ( :heavy_check_mark: )
| GET | /version | get version |( :heavy_check_mark: )
| GET | /config | get configuration | implements [Component Metadata](https://hackmd.io/sqedw7tHRye1RoAt5O108A?both#Component-Metadata) :question:

*Ban Rules* :soon:

| method | path | description | comment |
| ------ | ----- | --------------- | ------- |
| GET | /banrules | get all Ban Rules |
| POST | /banrules | add a new Ban Rule |
| GET | /banrules/:id | get specific ban Rule |
| PATCH | /banrules/:id | update specific ban rule |
| DELETE | /banrules/:id | delete specific ban rule |

+ [x] Get Certificate
+ [x] Get Components at Level $n-1$
+ names from https://en.wikipedia.org/wiki/XPath#Axis_specifiers
+ [x] receive registrations of Components in Level $n+1$
+ [x] receive deregistrations of Components from Level $n+1$
+ [x] get version
+ [x] get configuration
+ includes
+ get list of all API Methods
+ [x] Manage Ban-Rule List (CRUD)

*outgoing*

+ Register self in component with Level $n-1$
+ Unregister self from component with Level $n-1$
+ needs to be advertised to components in Level $n+1$

**CLI**
+ Create self
+ Kill self
+ Change Affiliation to Level $n-1$ component

:::info
*Level 0*
:::

## Keeper

All paths for Keeper-specific are prefixed by /keeper

**Core API**
+ [x] List Level1 Components

| method | path | description | comment |
| ------ | ----- | --------------- | ------- |
| GET | /keeper/components | List Level1 Components | |
| GET | /keeper/components/marketplaces | List Marketplaces | List only the Marketplaces registered in the current keeper
| GET | /keeper/components/marketplaces/:id | List one specific Marketplace | List only the Marketplace with ID:id in the current keeper |
| GET | /keeper/components/searchengines | List Search Engines | |
| GET | /keeper/components/searchengines/:id | List Search Engine with id | |

**Physical API** :soon:
+ join logical keeper
+ leave logical keeper
+ synchronize component lists

| method | path | description | comment |
| ------ | ----- | --------------- | ------- |
| GET | /keeper/logical/ | Get logical keeper info||
| POST | /keeper/logical/ | Join logical keeper||
| DELETE | /keeper/logical | Leave logical keeper||
| GET | /keeper/ | Join logical keeper||

**Discovery API (optional)**
+ add keeper to list of other logical keepers
+ list known logical keepers
+ get marketplaces of other logical keepers
+ get search engine of other logical keepers
+ get keepers of children

| method | path | description | comment |
| ------ | ----- | --------------- | ------- |
|

:::info
*Level 1*
:::

## Marketplace

**Core API**
+ List Level2 Components
+ Include pagination, filters based on metadata (essentially query params)

| method | path | description | comment |
| ------ | ----- | --------------- | ------- |
| GET | /marketplace/executionmanagers | Get all Execution Managers||
| GET | /marketplace/executionmanagers/:id | Get Execution Manager with ID||
| GET | /marketplace/assetmanagers | Get all Asset Mangers ||
| GET | /marketplace/assetmanagers/:id | Get Asset Manger wit ID ||

:::warning
what does the marketplace actually know? If it knows metadata, then there may need to be a way to update it, which should be a general function

**Note:** The metadata known by the MP is about the components (AM and EM)
:::

**Discovery API (optional)**
+ List logical Keepers
+ get List of L2-Components from other Marketplaces

---

**Users API**
+ Create new User
+ Authenticate User
+ Get self (User)

**Transactions API**
+ Get transaction rules (e.g. comission)
+ process transaction information
+ Get asset token from an asset consumer :question:

---

## Search Engine
**Core API**
+ return list of assets that match with Query
+ Discover Marketplaces, Asset Managers, Assets, Execution Managers and Node Executors below its Keeper and fetch their Metadata.

| method | path | description | comment |
| ------ | ----- | --------------- | ------- |
| GET | /searchengine/search?q=<term> | perform a Search with given "term"| Parameters can be keywords, ID, type TBD.|

:::danger
Proposed by Sergey, as part of an interface for the Search Engine

| method | path | description | comment |
| ------ | ----- | --------------- | ------- |
| TBD | Add | | |
| TBD | Find | | |
| TBD | Remove | | |
| TBD | Update? | | Remove+Add |
:::

**Discovery API (optional)**
+ List logical Keepers
+ get List of L2-Components from other Search engines :question:

:::info
*Level 2*
:::

## Asset Manager
**Core API**

| method | path | description | comment |
| ------ | ----- | --------------- | ------- |
|POST|/assetmanager/assets/:id/|Use an Asset|Payload includes userid, marketplace. *Discuss if there is a difference with .../:id/access/*|
|\*|/assetmanager/assets/:id/interact/…| Interact directyl with the API provided by an asset | If the Underlying Asset provides a REST API |
|GET|/assetmanager/assets/:id/operations/|List all interaction means for Asset with ID:id||
|GET|/assetmanager/assets/:id/constraints/|Get the constraints (restrictions) for Asset with ID:id||
|POST|/assetmanager/assets/:id/access/|creates and hands out credentials for accessing the asset directly |If the asset owner declares as public|

+ Get asset (Optional e-bill from Marketplace) (Asset Metadata in CRUD section)
+ Get restrictions
+ Get credentials to use from outside the ecosystem
+ provide list of interaction means
+ use asset
+ needs to include info like
+ username
+ what marketplace to register the transaction at (if any)
+ needs to be set, if the asset manager wants to get paid
+ list all assets (In CRUD section)

**CRUD asset(s)**

| method | path | description | comment |
| ------ | ----- | --------------- | ------- |
| GET | /assetmanager/assets/ | get all Assets registered in the Asset Manager| |
|POST|/assetmanager/assets/|Create a new asset|Payload contains the Asset Metadata|
| GET | /assetmanager/assets/:id | get specific Asset Metadata |
| PATCH | /assetmanager/assets/:id | update specific Asset Metadata|
| DELETE | /assetmanager/assets/:id | delete specific Asset Metadata from the Asset Manager |

**Billing API**

+ start transaction
+ submit info to TX
+ end TX

## Execution Manager
+ [name=ricardo,jorge] Execution Manager

**Core API**

+ start transaction
+ do Dry Run

| method | path | description | comment |
| ------ | ----- | --------------- | ------- |
| POST| /executionmanager/query/|Start transaction (Agora Query)| Payload contains the actual Query|
|POST| /executionmanager/query/dryrun/| Validate transaction (Agora Query) | Payload contains the actual Query|

**Billing API**

:::danger
TO BE DISCUSSED
:::

+ submit info to TX
+ end TX

:::info
*Level 3*
:::

## Node Executor

**Core API**

| method | path | description | comment |
| ------ | ----- | --------------- | ------- |
|POST|/nodexecutor/job/:id|Run a Job with ID:id| Creates and forward to the respective Node Executors. Payload contains Agora Execution Representation (XR) to be executed in the underlying Execution Platform and Agora XR to be forwarded.|
|GET| /nodexecutor/job/:id|Get the current status of the Job with ID:id||
|POST| /nodexecutor/job/:id/message|Send a message (from NE to NE) regarding query with ID:id. Content is in payload| one example is a message indicating successful completion of a local-execution-plan from NE 1. Indicating that NE2 can start computation on his part|

+ Run Agora Execution Representation
+ Get Job Status

:::info
*Primitive*
:::
## Asset

:::info
*Other use cases to consider from user perspective*
:::

:::danger
Define Asset Metadata
+ Check OpenML Schema
:::

+ If I found assets in Agora
+ I can execute it in the Ecosystem.
+ I can download the assets to execute in private Execution Layer.
+ I can get the raw assets and I assume the config of all underlying systems to run.
+ I can get the path and credentials and execute it on premises if the assets are not downloadable.

:::info
*Ecosystem use cases, where Agora provides the tools to support*
:::

+ Full Ecosystem = Keeper + Marketplace + Search Engine + Asset Manager + Optional(Search Engine) + Execution Manager + Node Executors
+ Asset Management Layer = Keeper + Marketplace + Asset Manager + Optional (Search Engine) => Yellow Pages
+ Execution Layer = Keeper + Marketplace + Execution Manager + Node Executor + Optional(Search Engine) => Agora recieves an Agora Query
+ Cloud like = Asset Management Layer with Compute and Storage Assets