9  Agent REST API

9.1 The Cloud Agent API

The only way to interact with our newly created Cloud Agent is trough the REST API, this means any action of the Cloud Agent such as establishing connections, creating Credential Schemas, issuing Verifiable Credentials, etc. will be triggered trough the agent API endpoints.

It is crucial to understand that the API is essentially an abstraction of the agent’s Identity Wallet. In our initial setup our agent is running on single-tenant mode, therefor it is managing a single default wallet which is assigned the following Entity ID (UUID) 00000000-0000-0000-0000-000000000000. You can confirm this by running the following command:

docker logs local-cloud-agent-1 | grep "default"


... Initializing default wallet.
... Default wallet seed is not provided. New seed will be generated.
... Entity created: Entity(00000000-0000-0000-0000-000000000000,default,00000000-0000-0000-0000-000000000000,1970-01-01T00:00:00Z,1970-01-01T00:00:00Z)

Later on the book, once we start building our example app, we will setup the agent in multi-tenant mode, meaning that a single agent instance will be capable of managing multiple wallets, we refer to those wallets as custodian wallets. This more advanced setup is useful when your users would want to delegate their Identity Wallet custody to a service instead of managing the wallet themselves.

Besides the _system/health endpoint we used earlier to confirm the agent version, there is one more endpoint used to debug runtime metrics:

curl http://localhost/cloud-agent/_system/metrics
# HELP jvm_memory_bytes_used  
# TYPE jvm_memory_bytes_used gauge
jvm_memory_bytes_used{area="heap",} 1.07522616E8
jvm_memory_bytes_used{area="nonheap",} 1.74044936E8
...

This will be useful when debugging a memory or performance issue or when developing.

9.2 OpenAPI Specification

The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to HTTP APIs. The Cloud Agent API documentation can be found at https://hyperledger.github.io/identus-docs/agent-api/ and besides being very detailed and always updated to the latest, it also comes with the OAS spec yaml file that will allow us to setup Postman to easily test our API or use the same OAS standard to auto generate code for client libraries on different language stacks. We will not attempt to repeat this API documentation in the book, rather lets focus on complement the existing documentation and explain with more detail how everything works.

9.3 APISIX Gateway

APISIX is in charge of proxying different services inside the container, exposing three routes trough the port you specified to the run.sh script (remember it runs on port 80 by default).

APISIX by default will just expose this services but trough plugins it can be setup as Ingress controller, load balancer, authentication and much more. You can read the APISIX documentation to learn more.

Warning

This is where CORS (Cross-Origin Resource Sharing) is setup, be default it will allow any origin, here you can restrict which domains should be allowed to connect to this endpoints. We will revisit this on our customization guide.

9.4 Swagger UI

Swagger UI it’s a visualization and interactive tool to explore an API. It’s automatically generated from your OpenAPI (formerly known as Swagger) Specification and it’s often used to support the API documentation.

Our Cloud Agent Docker file includes a container for Swagger UI that is exposed trough APISIX as explained earlier. This means you can use this tool right away after the agent is running.

To use it, just open http://localhost/apidocs/ in your browser and from the server list select:

  • http://localhost/cloud-agent - The local instance of the Cloud Agent behind the APISIX proxy.

Then, click the Authorize button and a small modal window will popup, in there you need to define an apikey, even if by default you haven’t defined one, this means you can put any value in here, of course later in the book when we set an actual apikey you will need to use it here, for now just use test as value and it should be fine.

After authorizing, the modal should look like this:

Swagger UI Apikey Modal

You can close that modal window and try your first request, click to expand the GET /connections endpoint and click Try it out button, that will enable the text inputs for any available parameters, for now, all three parameters should be blank (offet, limit, thid).

Finally, just click the Execute button to actually perform the request. This should return something like this:

{ "contents": [], "kind": "ConnectionsPage", "self": "", "pageOf": "" }

Congratulations! you have connected to the API and asked for a list of connections, right now there are no connections so the empty array you get back is correct.

Note

You can use Swagger UI to copy curl commands that you can paste in your terminal, this will run exactly the same API request. For example:

curl -X 'GET' \
  'http://localhost/cloud-agent/connections' \
  -H 'accept: application/json' \
  -H 'apikey: test'
{"contents":[],"kind":"ConnectionsPage","self":"","pageOf":""}

9.5 Postman

Postmanis perhaps the most popular API tool among developers, it allow us to easily interact and debug API endpoints but has many killer feature like enabling teams to share and work together on the same API, run automated tests, automatically renew tokens, keeps the state of your interactions with the API, copy code snippets to make API calls over many languages, etc. So it’s really a better overall option versus the Swagger UI interface or just directly using curl.

The big time saver for us is that because it supports OAS, we can easily import the whole API definition. So, let’s try it:

  1. If you don’t already have it, first you should Download Postman and Sign Up for a free account.
  2. Head to the API docs and click the Download button, or copy this direct link https://hyperledger.github.io/identus-docs/redocusaurus/plugin-redoc-0.yaml
  3. Inside Postman, go to File -> Import and either drag & drop your yaml file if you downloaded it or paste the URL in the box, this will auto advance to the next step.
  4. On the “How to import” step select “OpenAPI 3.0 with a Postman Collection” and click import.

If everything goes correctly, you should see “Identus Cloud Agent API Reference” in your collections.

9.6 Tutorials

The official documentation contains a tutorials section with detailed walkthroughs for each of the most important interactions like connecting to another peer, managing DIDs, managing VC Schemas, issuing a VC, etc. We highly encourage you to follow those and get familiar with the API, this will come in very handy very soon when we start building our own example app.