Skip to main content

How to consume a REST API

The Genesis HTTP Client provides a simple way of integrating external REST services with the Genesis Platform. It contains an intuitive DSL for making HTTP requests, so that you can integrate your Request Servers and Event Handlers seamlessly with external applications.

All the standard HTTP requests are supported: GET, POST, PUT, DELETE.

To handle errors, there is built-in support for retries and error callbacks.

And pagination is supported for Request Servers.

You can choose which way to implement the integration:

  • using the client directly
  • generating type-safe code via OpenAPI
  • creating a Data Pipeline

Example​

To show how to start integrating with REST services, we have provided an example application.

Download, view and run

The example is within one complete example application, which includes a front end so that you can run and see the data.

You can clone the repo to see the code - which includes comments at the key points to highlight what is being specified - and run a provided docker file to REST integrations in action.

There is a main README file that gives an overview of the application, and two subsequent README file that explains the two main approaches to integration:

  • REST Integration with Open API and using HTTP clients directly
  • Integrating External APIs with Pipelines

You'll find links to these subjects as you step through the example application.

Open API REST integration with code generation​

Starting from an Open API/Swagger specification, this example generates type-safe code and then embeds it in Genesis components such as the Request Server.

Here you will find stepped instructions for recreating this example, including:

  • adding the required dependencies
  • configuring the Open API plugin
  • mapping parameters to handle pagination in the Request Server
  • adding the code to requestReply in a Request Server

Using HTTP clients directly​

If you do not have a specification to generate code from, you can define your own data classes and use them with the Genesis HTTP Client, or work with the raw response.

Our example uses the Genesis HTTP Client, but you can use any client that you are familiar with, such as Ktor.

Displaying the results in the front end​

There are also instructions for creating a grid to view the data in the front end, including:

  • adding the dependencies
  • registering modules in the .ts page
  • defining the grid, including handling infinite scrolling and pagination

Using Data Pipeline to integrate external APIs​

You can also integrate your external API with data pipelines. These pipelines can be triggered by other components and reused across your application, reducing duplication.

A separate example, which has its own README file, shows you how to use the Data Pipeline this way, including instructions for displaying the results on the front end.