# Generating an API Client

Use [OpenAPI Generator](https://openapi-generator.tech/) to scaffold a typed, ready-to-use client from the Bookable Bookings API spec. This removes the need to hand-write HTTP calls, models, or serialization logic.

## Prerequisites

OpenAPI Generator requires **Java 11+** to run. Install it once, then use either the CLI wrapper or the `npx` approach — no permanent global install needed.


```bash
# Check Java version
java -version
```

Install the CLI wrapper via npm (recommended for Node-based projects):


```bash
npm install @openapitools/openapi-generator-cli --save-dev
```

Or run it on-demand without installing:


```bash
npx @openapitools/openapi-generator-cli version
```

## Download the spec


```bash
curl -O https://bookable.redocly.app/_spec/apis/BookingApi.yml
```

Or reference it directly in the generate command using the URL — no local copy needed.

## Generate a client

Run `generate` with the target language generator, the spec file, and an output directory.

TypeScript

```bash
npx @openapitools/openapi-generator-cli generate \
  -i BookingApi.yml \
  -g typescript-fetch \
  -o ./src/bookable-client \
  --additional-properties=supportsES6=true,npmName=bookable-client
```

Python

```bash
npx @openapitools/openapi-generator-cli generate \
  -i BookingApi.yml \
  -g python \
  -o ./bookable-client \
  --additional-properties=packageName=bookable_client
```

Java

```bash
npx @openapitools/openapi-generator-cli generate \
  -i BookingApi.yml \
  -g java \
  -o ./bookable-client \
  --additional-properties=groupId=com.example,artifactId=bookable-client,java8=true
```

C#

```bash
npx @openapitools/openapi-generator-cli generate \
  -i BookingApi.yml \
  -g csharp \
  -o ./BookableClient \
  --additional-properties=packageName=BookableClient,targetFramework=net6.0
```

Replace `BookingApi.yml` with the remote URL `https://bookable.redocly.app/_spec/apis/BookingApi.yml` to always generate from the latest published spec.

## Configure the generated client

The generated client defaults to the base URL defined in the spec. Override it at runtime and inject the OAuth token before making requests.

TypeScript

```typescript
import { Configuration, BookingsApi } from './src/bookable-client';

const config = new Configuration({
  basePath: 'https://api-sandbox.bookabletech.com', // or https://api.bookabletech.com
  accessToken: async () => {
    // Return a valid Bearer token — fetch from your token store or refresh if needed
    return myTokenStore.getAccessToken();
  },
});

const api = new BookingsApi(config);

const availability = await api.getAvailability({
  operatorId: 'op_123',
  date: '2026-06-15',
  partySize: 2,
});
```

Python

```python
import bookable_client
from bookable_client.api import bookings_api

configuration = bookable_client.Configuration(
    host="https://api-sandbox.bookabletech.com"
)
configuration.access_token = my_token_store.get_access_token()

with bookable_client.ApiClient(configuration) as api_client:
    api = bookings_api.BookingsApi(api_client)
    availability = api.get_availability(operator_id="op_123", date="2026-06-15", party_size=2)
```

Java

```java
ApiClient client = new ApiClient();
client.setBasePath("https://api-sandbox.bookabletech.com");
client.setAccessToken(myTokenStore.getAccessToken());

BookingsApi api = new BookingsApi(client);
AvailabilityResponse availability = api.getAvailability("op_123", "2026-06-15", 2);
```

C#

```csharp
var config = new Configuration
{
    BasePath = "https://api-sandbox.bookabletech.com",
    AccessToken = myTokenStore.GetAccessToken(),
};

var api = new BookingsApi(config);
var availability = await api.GetAvailabilityAsync("op_123", "2026-06-15", 2);
```

## Token management

The generated client does not handle token refresh automatically. Use a wrapper or middleware to fetch a token via the OAuth client credentials flow before each request, or cache it and refresh when it is about to expire.

See [Authentication](/getting-started/auth) for the full token endpoint and request format.

## Pinning the generator version

To ensure reproducible builds, pin the generator version in your project config:


```json
// openapitools.json (created automatically on first run)
{
  "$schema": "node_modules/@openapitools/openapi-generator-cli/config.schema.json",
  "spaces": 2,
  "generator-cli": {
    "version": "7.10.0"
  }
}
```

Run `npx @openapitools/openapi-generator-cli version-manager list` to see available versions.

## Available generators

OpenAPI Generator supports 50+ languages and frameworks. Run the following to list all options:


```bash
npx @openapitools/openapi-generator-cli list
```

Common choices for Bookable integrations:

| Generator | Output |
|  --- | --- |
| `typescript-fetch` | TypeScript with native fetch |
| `typescript-axios` | TypeScript with Axios |
| `javascript` | Plain JavaScript (CommonJS) |
| `python` | Python (requests) |
| `java` | Java (OkHttp + Gson) |
| `csharp` | C# (.NET) |
| `go` | Go |
| `ruby` | Ruby |
| `php` | PHP |


## Related

- [Authentication](/getting-started/auth) — OAuth 2.0 token flow and code examples
- [API Reference](/apis/production/bookingapi) — full Bookings API spec
- [Using Postman](/resources/postman-import) — test endpoints without code
- [Quickstart](/getting-started/quickstart) — make your first booking