API definition using Effect

With @effect/platform an API is defined by a collection of HttpApiGroup.

A HttpApiGroup consists of a class extending HttpApiGroup.make each with its own identifier and a collection of endpoints.

api.ts
export class PaddleApiGroup extends HttpApiGroup.make("paddle") {}

Each endpoint is defined with HttpApiEndpoint:

  • Method
  • Unique identifier (string)
  • Path
  • Parameters (success, errors, headers, payload and more)

The project contains two endpoints:

  • /paddle/webhook: receives webhook events from Paddle
  • /paddle/product/:slug: used by the client to request products information
api.ts
export class PaddleApiGroup extends HttpApiGroup.make("paddle")
  .add(
    HttpApiEndpoint.post("webhook", "/paddle/webhook")
      .addError(ErrorWebhook)
      .addSuccess(Schema.Boolean)
      .setHeaders(
        Schema.Struct({
          "paddle-signature": Schema.NonEmptyString,
        })
      )
  )
  .add(
    HttpApiEndpoint.get("product", "/paddle/product/:slug")
      .addError(ErrorInvalidProduct)
      .addSuccess(
        Schema.Struct({
          product: PaddleProduct,
          price: PaddlePrice,
        })
      )
      .setPath(
        Schema.Struct({
          slug: Schema.NonEmptyString,
        })
      )
  ) {}

The HttpApiGroup is then added to HttpApi which exports the full API definition:

api.ts
export class MainApi extends HttpApi.make("MainApi").add(PaddleApiGroup) {}