api-client-development

API Client Development

This skill covers creating typed API clients using OpenAPI specifications, with proper authentication and OAuth scope handling. It builds on the patterns in SDK Module Development.

Overview

API clients in this project use:

• openapi-fetch: Type-safe HTTP client generated from OpenAPI specs
• openapi-typescript: Generates TypeScript types from OpenAPI specs
• Middleware pattern: Auth and logging injected via openapi-fetch middleware

Creating a New API Client

1. Add the OpenAPI Spec

Place the spec in packages/b2c-tooling-sdk/specs/:

specs/
├── custom-apis-v1.yaml    # YAML or JSON
├── slas-admin-v1.yaml
└── ods-api-v1.json

2. Update Type Generation Script

In packages/b2c-tooling-sdk/package.json, add to the generate script:

{
  "scripts": {
    "generate:types": "openapi-typescript specs/data-api.json -o src/clients/ocapi.generated.ts && openapi-typescript specs/newapi-v1.yaml -o src/clients/newapi.generated.ts"
  }
}

Run generation:

pnpm --filter @salesforce/b2c-tooling-sdk run generate:types

3. Create the Client Module

// src/clients/newapi.ts
import createClient, {type Client} from 'openapi-fetch';
import type {AuthStrategy} from '../auth/types.js';
import type {paths, components} from './newapi.generated.js';
import {createAuthMiddleware, createLoggingMiddleware} from './middleware.js';

// Re-export generated types for consumers
export type {paths, components};

// Client type alias
export type NewApiClient = Client<paths>;

// Config interface
export interface NewApiClientConfig {
  hostname: string;
  // Add API-specific config here
}

// Factory function
export function createNewApiClient(
  config: NewApiClientConfig,
  auth: AuthStrategy
): NewApiClient {
  const client = createClient<paths>({
    baseUrl: `https://${config.hostname}/api/v1`,
  });

  // Middleware order: auth first (runs last), logging last (sees complete request)
  client.use(createAuthMiddleware(auth));
  client.use(createLoggingMiddleware('NEWAPI'));

  return client;
}