Skip to main content

HTTP Client

Install​

npm install @basketry/typescript-http-client

Basic Usage​

basketry.config.json
{
  "source": "petstore.json",
  "parser": "@basketry/openapi-3",
  "generators": [
    "@basketry/typescript",
    "@basketry/typescript-dtos",
    "@basketry/typescript-http-client",
    "@basketry/zod"
  ],
  "options": {
    "httpClient": { "validation": "zod" }
  },
  "output": "src"
}

File Structure​

This generator will create an http-client.ts file that contains an HTTP client for the API. This client will have methods for each operation defined in the source schema.


my-project/
├── node_modules/
├── src/
│ ├── v1/                <-- generated
│ │ ├── dtos
│ │ │ ├── mappers.ts
│ │ │ ├── README.md
│ │ │ └── types.ts
│ │ ├── http-client.ts   <-- generated
│ │ ├── schemas.ts
│ │ └── types.ts
│ └── index.ts
├── .gitignore
├── basketry.config.json
├── package.json
├── petstore.json
└── README.md

Options​

This generator depends on the @basketry/typescript, @basketry/typescript-dtos, and @basketry/zod generators and all of their applied options will also apply to files emitted by this generator.

See:

This generator depends on files generated by the @basketry/typescript, @basketry/typescript-dtos, and @basketry/zod generators. In most cases, those files will exist within the same directory as the generated http-client.ts file.

By default, the generated code will import its dependencies as follows:

src/v1/http-client.ts
import * as dtos from "./dtos/types";
import * as mappers from "./dtos/mappers";
import * as schemas from "./schemas";
import * as types from "./types";

If those modules are located in a different directory, you can use the following options to specify custom import paths. These paths can be any string that you would normally require or import. This can be useful when generated dependencies are distributed as part of a library or package.

dtosImportPath​

  • Type: string - specifies the path for the DTO import.
basketry.config.json
{
  "source": "petstore.json",
  "parser": "@basketry/openapi-3",
  "generators": [
    "@basketry/typescript",
    "@basketry/typescript-dtos",
    "@basketry/typescript-http-client",
    "@basketry/zod"
  ],
  "output": "src",
  "options": {
    "httpClient": {
      "dtosImportPath": "@petstore/sdk/lib/dtos/types",
      "validation": "zod"
    }
  }
}

This option as configured will now emit the following code at the top of the generated file:

src/v1/http-client.ts
import * as mappers from "@petstore/sdk/lib/dtos/types";

mappersImportPath​

  • Type: string - specifies the path for the mappers import.
basketry.config.json
{
  "source": "petstore.json",
  "parser": "@basketry/openapi-3",
  "generators": [
    "@basketry/typescript",
    "@basketry/typescript-dtos",
    "@basketry/typescript-http-client",
    "@basketry/zod"
  ],
  "output": "src",
  "options": {
    "httpClient": {
      "mappersImportPath": "@petstore/sdk/lib/dtos/mappers",
      "validation": "zod"
    }
  }
}

This option as configured will now emit the following code at the top of the generated file:

src/v1/http-client.ts
import * as mappers from "@petstore/sdk/lib/dtos/mappers";

schemasImportPath​

  • Type: string - specifies the path for the Zod schemas import.
basketry.config.json
{
  "source": "petstore.json",
  "parser": "@basketry/openapi-3",
  "generators": [
    "@basketry/typescript",
    "@basketry/typescript-dtos",
    "@basketry/typescript-http-client",
    "@basketry/zod"
  ],
  "output": "src",
  "options": {
    "httpClient": {
      "schemasImportPath": "@petstore/sdk/lib/schemas",
      "validation": "zod"
    }
  }
}

This option as configured will now emit the following code at the top of the generated file:

src/v1/http-client.ts
import * as schemas from "@petstore/sdk/lib/schemas";

typesImportPath​

  • Type: string - specifies the path for the types import.
basketry.config.json
{
  "source": "petstore.json",
  "parser": "@basketry/openapi-3",
  "generators": [
    "@basketry/typescript",
    "@basketry/typescript-dtos",
    "@basketry/typescript-http-client",
    "@basketry/zod"
  ],
  "output": "src",
  "options": {
    "httpClient": {
      "typesImportPath": "@petstore/sdk/lib/types",
      "validation": "zod"
    }
  }
}

This option as configured will now emit the following code at the top of the generated file:

src/v1/http-client.ts
import * as types from "@petstore/sdk/lib/types";

validation​

  • Type: zod or native - specifies the validation strategy to use for the HTTP Client. zod will become the default value in basketry 0.2—unitl then it needs to be specified explicitly.
Deprecated

Native validation is deprecated and will not receive updates. Please use the Zod Generator instead.

basketry.config.json
{
  "source": "petstore.json",
  "parser": "@basketry/openapi-3",
  "generators": [
    "@basketry/typescript",
    "@basketry/typescript-dtos",
    "@basketry/typescript-http-client",
    "@basketry/zod"
  ],
  "output": "src",
  "options": {
    "httpClient": {
      "validation": "zod"
    }
  }
}

Examples​

You can use the following examples to see how to use the generated HTTP Client. In both the browser and Node environments, you can pass any method that implements the fetch interface to the service class. You can use the native fetch method, a wrapped version of fetch, or a custom library of your choosing.

Browser​

src/index.ts
import { HttpPetService, PetService } from "./v1/http-client";

const petService: PetService = new HttpPetService(window.fetch.bind(window), {
  root: "https://api.example.com/v1",
});

export default petService;
warning

Note that if you pass window.fetch to a service class, you need to rebind the fetch method to the window object.

If you don't, the fetch method will fail to execute in the browser environment. No request will be sent, and the console will display the error "TypeError: Failed to execute 'fetch' on 'Window': Illegal invocation".

Node​

src/index.ts
import { HttpPetService, PetService } from "./v1/http-client";

const petService: PetService = new PetService(fetch, {
  root: "https://api.example.com/v1",
});

export default petService;