---
# System prepended metadata

title: AGORA PoC v0.2 | API

---

[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

