# Generate an SDK

This page is for developers who want a typed VBAPI client generated from the OpenAPI description instead of writing HTTP calls by hand. It covers where to get the description, what to know about it before you generate, and the commands for three common generators.

Not yet tested end to end
The generator commands below use each tool's documented options, but generating, compiling, and calling VBAPI with the resulting clients has not yet been tested for this API. Expect to adjust options for your language and tool version. The Redocly bundling step in [Generate a smaller client](#generate-a-smaller-client) has been run against the current description.

## Download the OpenAPI description

The portal publishes the same description that drives the [API reference](/openapi/vbasoftware/vbasoftware.api):

- JSON: [`/static/openapi/vbasoftware.api.json`](/assets/vbasoftware.api.c385ade9eac6330cb4516f0a85b8a7a6f34b5581270043439bddcddab5a39619.2defd4af.json)
- YAML: [`/_bundle/openapi/vbasoftware/vbasoftware.api.yaml?download`](/_bundle/openapi/vbasoftware/vbasoftware.api.yaml?download)


Both paths are relative to the portal's address. Save the file next to your project as `vbasoftware.api.yaml` (or `.json`); the commands below assume that name.

## What to know about the description

- **It is large.** It describes 5,348 operations on 2,952 paths, with about 2,860 schemas, and the YAML file is about 11 MB. A client for all of it is a very large codebase and takes a while to generate and compile. If you only use a few areas, [generate a smaller client](#generate-a-smaller-client).
- **Set the base URL yourself.** Configure your client with the production base URL, `https://vbapi.vbasoftware.com/vbasoftware`, rather than relying on the `servers` entry in the file.
- **Authentication is declared per operation.** Data operations require the `x-api-key` header and a bearer token; `POST /user-authentication` requires `x-api-key` and HTTP Basic; a few operations need only `x-api-key`. Generated clients usually read this correctly. The bearer token is the `idToken` from [`POST /user-authentication`](/openapi/vbasoftware/vbasoftware.api/user/userauthentication), and it expires after `expiresIn` seconds, so your code still has to log in and refresh it (see [Authentication and tokens](/developer-portal/concepts/authentication)).
- **The database header is a parameter.** `vbasoftware-database` is a required header parameter on almost every operation, so most generated methods take it as an argument. Login also takes `vbasoftware-client-id` and `vbasoftware-client-code` as parameters.
- **Send a descriptive `User-Agent`.** VBAPI accepts requests without one, but a value that names your integration helps VBA support find your calls. Generated clients often send a generic value; set your own.
- **Responses are wrapped.** Each operation returns an envelope type (for example `AuthVBAResponse`) with `data`, `error`, and `debug`, so generated code reads results from `data` (see [Requests and responses](/developer-portal/concepts/requests-and-responses)).
- **Path parameter names are not consistent.** For example `/providers/{providerID}/clia-certificates` and `/providers/{providerId}/rates/{providerRateKey}/criterias` spell the provider ID differently, and `/vbaprocesses/{vBAProcessKey}/types/{vBAProcessType}` and `/disenroll-logs/{DisenrollLog_Key}` use different styles for keys. Generated method arguments follow these names.
- **Tags overlap.** There are 882 tags, and some operations have more than one (for example `Auth` and `Adv. Auth`), so a generator that groups operations by tag can put the same operation in two classes.


## Generate a client

Pick one generator. Each needs to be installed first; follow the linked instructions.

### OpenAPI Generator

[OpenAPI Generator](https://openapi-generator.tech/docs/installation/) needs Java. One way to install it is the npm wrapper, `npm install -g @openapitools/openapi-generator-cli`. Then:

```bash
# C#
openapi-generator-cli generate -i vbasoftware.api.yaml -g csharp -o ./vbapi-csharp --additional-properties=packageName=YourCompany.Vbapi

# Python
openapi-generator-cli generate -i vbasoftware.api.yaml -g python -o ./vbapi-python --additional-properties=packageName=vbapi_client

# TypeScript with axios
openapi-generator-cli generate -i vbasoftware.api.yaml -g typescript-axios -o ./vbapi-typescript
```

`-i` is the input file, `-g` the generator, and `-o` the output folder. Each generator has its own `--additional-properties`; run `openapi-generator-cli config-help -g <generator>` to list them, and see the [generator list](https://openapi-generator.tech/docs/generators/).

### NSwag (C#)

[NSwag](https://github.com/RicoSuter/NSwag) generates a single C# client class. Install the command-line tool with `dotnet tool install --global NSwag.ConsoleCore`, then:

```bash
nswag openapi2csclient /input:vbasoftware.api.json /output:VbapiClient.cs /namespace:YourCompany.Vbapi /classname:VbapiClient
```

### Kiota

[Kiota](https://learn.microsoft.com/openapi/kiota/) generates clients for C#, Python, TypeScript, and other languages, and can include only some paths. Install it with `dotnet tool install --global Microsoft.OpenApi.Kiota`, then:

```bash
kiota generate --openapi vbasoftware.api.yaml --language CSharp --class-name VbapiClient --namespace-name YourCompany.Vbapi --output ./VbapiClient --include-path "/auths/**"
```

Use `--language Python` or `--language TypeScript` for the other languages. Repeat `--include-path` for each area you need, or omit it to generate everything.

## Generate a smaller client

The [Redocly CLI](https://redocly.com/docs/cli/) can cut the description down to the tags you need before you generate. Install it with `npm install -g @redocly/cli`, and create a `redocly.yaml` next to the downloaded file:

```yaml
apis:
  vbapi-auth:
    root: ./vbasoftware.api.yaml
    decorators:
      filter-in:
        property: tags
        value:
          - Auth
          - Auth Procedure Codes
          - Auth Diagnostic Codes
        matchStrategy: any
      remove-unused-components: on
```

Then bundle it:

```bash
redocly bundle vbapi-auth -o vbapi-auth.yaml
```

With the three authorization tags above, the result has 22 operations and 16 schemas (about 85 KB), and bundling takes a few seconds. Generate your client from `vbapi-auth.yaml` with any of the commands above. Tag names are the section names in the left navigation of the API reference.

## Keep it current

The description changes when VBAPI changes. Regenerate your client when you pick up a new release, and check the [changelog](/developer-portal/reference/changelog) for changes that affect you. If you commit the generated code, you can review each regeneration as a diff.

## Related

- [Quick start](/developer-portal/get-started/quick-start), which makes a first call without a generated client
- [Authentication and tokens](/developer-portal/concepts/authentication)
- [Errors and troubleshooting](/developer-portal/concepts/errors)