Using The API
Covenant comes with a powerful API that can be used to create Covenant extensions, perform automation, gain access to data not presented in the web interface, or debug during development.
Covenant also uses Swagger UI, which provides a UI to visualize and interact with Covenant's API.
To interact with the API using Swagger UI, navigate to: https://<covenant-address>:7443/swagger
This interface allows you to interact with Covenant's API endpoints and provides helpful templates for what an API call should look like. Covenant's API requires authentication for security purposes, so you must logon via the POST /api/users/login API endpoint prior to interacting with any of the other endpoints.
Clicking on the POST /api/users/login endpoint should reveal a textbox that you can input the required information for the API. Clicking on the "Example Value" box on the right will place a template into the textbox for you. For this call, the username and password parameters should be completed with valid information, and clicking on the "Try it out!" button will execute the API call.
Covenant will respond with a success field indicating whether or not the logon succeeded. If it did succeed, the covenantToken field should contain a JWT that we can use for authentication for future API calls. We can provide this value to the Swagger UI page by clicking on the Authorize button at the top of the page.
Clicking the Authorize button reveals a dialog prompt. You should place the string "Bearer " into this field and click Authorize, which informs Swagger UI of our credentials for future API requests.
Now, we should be able to use any of Covenant's API endpoints from this interface!
Covenant includes a built-in C# API client that can be used in other projects to extend or automate the functionality of Covenant. The built-in client can be found here.
Including this client in an C# project will introduce the Covenant.API namespace, which can be used to interact with Covenant's API. You can find examples of this API in use within Covenant itself here.
Covenant distributes the OpenAPI specification for the Covenant API, which can be found here.
OpenAPI specifications can be used to generate API client using various API code generators. Covenant's C# API client is generated by using autorest. Autorest can generate clients in various languages, such as: C#, Python, Java, Go, etc. You can use Autorest, Swagger CodeGen, or any other OpenAPI compatible tools to generate new API clients.