You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: AdminAPI.md
+65-65Lines changed: 65 additions & 65 deletions
Original file line number
Diff line number
Diff line change
@@ -2,72 +2,72 @@
2
2
3
3
## Using the OpenAPI (Swagger) Interface
4
4
5
-
ACA-Py provides an OpenAPI-documented REST interface for administering the agent's internal state and sparking communication with connected agents.
5
+
ACA-Py provides an OpenAPI-documented REST interface for administering the agent's internal state and initiating communication with connected agents.
6
6
7
-
To see the specifics of the supported endpoints as well as the expected request and response formats it is recommended to run the `aca-py` agent with the `--admin {HOST} {PORT}` and `--admin-insecure-mode` command line parameters, which exposes the OpenAPI UI on the provided port for interaction via a web browser. Production deployments should run the agent with `--admin-api-key {KEY}` and add the `X-API-Key: {KEY}` header to all requests instead of running the agent with the `--admin-insecure-mode` parameter.
7
+
To see the specifics of the supported endpoints, as well as the expected request and response formats, it is recommended to run the `aca-py` agent with the `--admin {HOST} {PORT}` and `--admin-insecure-mode` command line parameters. This exposes the OpenAPI UI on the provided port for interaction via a web browser. For production deployments, run the agent with `--admin-api-key {KEY}` and add the `X-API-Key: {KEY}` header to all requests instead of using the `--admin-insecure-mode` parameter.
8
8
9
9
10
10
11
11
To invoke a specific method:
12
12
13
-
* scroll to and find that endpoint;
14
-
* click on the endpoint name to expand its section of the UI;
15
-
* click on the Try it out button;
16
-
* fill in any data necessary to run the command;
17
-
* click Execute;
18
-
* check the response to see if the request worked as expected.
13
+
* Scroll to and find that endpoint;
14
+
* Click on the endpoint name to expand its section of the UI;
15
+
* Click on the Try it out button;
16
+
* Fill in any data necessary to run the command;
17
+
* Click Execute;
18
+
* Check the response to see if the request worked as expected.
19
19
20
-
The mechanical steps are easy, it’s fourth step from the list above that can be tricky. Supplying the right data and, where JSON is involved, getting the syntax correct - braces and quotes can be a pain. When steps don’t work, start your debugging by looking at your JSON. You may also choose to use a REST client like Postman or Insomnia which will provide syntax highlighting and other features to simplify the process.
20
+
The mechanical steps are easy; however, the fourth step from the list above can be tricky. Supplying the right data and, where JSON is involved, getting the syntax correct—braces and quotes can be a pain. When steps don't work, start your debugging by looking at your JSON. You may also choose to use a REST client like Postman or Insomnia, which will provide syntax highlighting and other features to simplify the process.
21
21
22
-
Because API methods will often kick off asynchronous processes, the JSON response provided by an endpoint is not always sufficient to determine the next action. To handle this situation as well as events triggered due to external inputs (such as new connection requests), it is necessary to implement a webhook processor, as detailed in the next section.
22
+
Because API methods often initiate asynchronous processes, the JSON response provided by an endpoint is not always sufficient to determine the next action. To handle this situation, as well as events triggered by external inputs (such as new connection requests), it is necessary to implement a webhook processor, as detailed in the next section.
23
23
24
-
The combination of an OpenAPI client and webhook processor is referred to as an ACA-Py Controller and is the recommended method to define custom behaviours for your ACA-Py-based agent application.
24
+
The combination of an OpenAPI client and webhook processor is referred to as an ACA-Py Controller and is the recommended method to define custom behaviors for your ACA-Py-based agent application.
25
25
26
26
## Administration API Webhooks
27
27
28
28
When ACA-Py is started with the `--webhook-url {URL}` command line parameter, state-management records are sent to the provided URL via POST requests whenever a record is created or its `state` property is updated.
29
29
30
-
When a webhook is dispatched, the record `topic` is appended as a path component to the URL, for example:`https://webhook.host.example` becomes `https://webhook.host.example/topic/connections` when a connection record is updated. A POST request is made to the resulting URL with the body of the request comprised by a serialized JSON object. The full set of properties of the current set of webhook payloads are listed below. Note that empty (null-value) properties are omitted.
30
+
When a webhook is dispatched, the record `topic` is appended as a path component to the URL. For example,`https://webhook.host.example` becomes `https://webhook.host.example/topic/connections` when a connection record is updated. A POST request is made to the resulting URL with the body of the request comprising a serialized JSON object. The full set of properties of the current set of webhook payloads are listed below. Note that empty (null-value) properties are omitted.
31
31
32
-
####Pairwise Connection Record Updated (`/connections`)
32
+
### Pairwise Connection Record Updated (`/connections`)
33
33
34
-
*`connection_id`: the unique connection identifier
*`presentation_proposal_dict`: the presentation proposal message
99
+
*`presentation_request`: (Indy) presentation request (also known as proof request)
100
+
*`presentation`: (Indy) presentation (also known as proof)
101
+
*`verified`: (string) whether the presentation is verified: `true` or `false`
102
+
*`auto_present`: (boolean) prover choice to auto-present proof as verifier requests
103
+
*`error_msg`: the previous error message
104
104
105
-
## API Standard Behaviour
105
+
## API Standard Behavior
106
106
107
107
The best way to develop a new admin API or protocol is to follow one of the existing protocols, such as the Credential Exchange or Presentation Exchange.
108
108
109
109
The `routes.py` file contains the API definitions - API endpoints and payload schemas (note that these are not the Aries message schemas).
110
110
111
-
The payload schemas are defined using [marshmallow](https://marshmallow.readthedocs.io/) and will be validated automatically when the API is executed (using a middleware). (This raises a status `422` HTTP response with an error message if the schema validation fails.)
111
+
The payload schemas are defined using [marshmallow](https://marshmallow.readthedocs.io/) and will be validated automatically when the API is executed (using middleware). (This raises a status `422` HTTP response with an error message if the schema validation fails.)
112
112
113
-
API endpoints are defined using [aiohttp_apispec](https://github.com/maximdanilchenko/aiohttp-apispec) tags (e.g. `@doc`, `@request_schema`, `@response_schema` etc.) which define the input and output parameters of the endpoint. API url paths are defined in the `register()` method and added to the swagger page in the `post_process_routes()` method.
113
+
API endpoints are defined using [aiohttp_apispec](https://github.com/maximdanilchenko/aiohttp-apispec) tags (e.g. `@doc`, `@request_schema`, `@response_schema` etc.) which define the input and output parameters of the endpoint. API URL paths are defined in the `register()` method and added to the Swagger page in the `post_process_routes()` method.
114
114
115
-
The API's should return the following HTTP status:
115
+
The APIs should return the following HTTP status:
116
116
117
-
* HTTP 200 for successful API completion, with appropriate response
118
-
* HTTP 400 (or appropriate 4xx code) (with an error message) for errors on input parameters (i.e. the user can retry with different parameters and potentially get a successful API call)
119
-
* HTTP 404 if a record is expected and not found (generally for GET requests that fetch a single record)
120
-
* HTTP 500 (or appropriate 5xx code) if there is some other processing error (i.e. won't make any difference what parameters the user tries) with an error message
117
+
* HTTP 200 for successful API completion, with an appropriate response
118
+
* HTTP 400 (or appropriate 4xx code) (with an error message) for errors on input parameters (i.e., the user can retry with different parameters and potentially get a successful API call)
119
+
* HTTP 404 if a record is expected and not found (generally for GET requests that fetch a single record)
120
+
* HTTP 500 (or appropriate 5xx code) if there is some other processing error (i.e., it won't make any difference what parameters the user tries) with an error message
121
121
122
-
..and should not return:
122
+
...and should not return:
123
123
124
-
* HTTP 500 with a stack trace due to untrapped error (we should handle error conditions with a 400 or 404 response, and catch errors and provide a meaningful error message)
124
+
* HTTP 500 with a stack trace due to an untrapped error (we should handle error conditions with a 400 or 404 response and catch errors, providing a meaningful error message)
0 commit comments