clients.md

Creating HTTP Clients

The code generated by OpenAPI and AsyncAPI generators requires the user to provide an HTTPClient or WebSocketClient instance respectively.

The original intent is to create such instances in the consumer's application; however, some predefined clients may be added in the future. This guide describes basic steps to create one.

Defining a return type

In order to support the desired return type, the generated code must know how to perform some basic operations over that type, such as creating a "successful" or "failed" response object, or applying a given transform function to the response. These operations are abstracted via the MonadThrow interface from the fp-ts library.

Some common types already have corresponding Monad implementations, while for others you might have to implement one from scratch. For an example of how this can be done and what functions are required, check how the Monad is implemented for RxJS's Observable in the fp-ts-rxjs package.

Implementing the actual HTTP requests logic

Once the Monad implementation is available, just two methods need to be added to form a working HTTPClient: throwError and request. As can be seen from their signatures, they create a "failed" response and make actual HTTP calls, respectively.

Considering the above, an HTTPClient for RxJS could be defined as follows:

import { Monad } from "fp-ts-rxjs/lib/Observable";
import { throwError } from "rxjs";

const rxjsHttpClient: HTTPClient1<"Observable"> = {
  ...Monad,
  request: (req) => {
    return ajax({
      url: req.url,
      method: req.method,
      // add the logic to handle `req.body` and other parameters
    }).pipe();
  },
  throwError,
};