Skip to Content
Engineering11 Documentation 🔥
BackendServer API PackagesREST Client

REST Client API

HTTP client wrapper with authentication, retry logic, and error handling.

What It Does

The REST Client API provides a feature-rich HTTP client built on Axios with pre-configured authentication, retry logic, error standardization, and Server-Sent Events support. It includes specialized clients for inter-service communication with automatic credential management.

Key Capabilities

  • Multiple Auth Strategies: Bearer tokens, API keys, GCP OIDC, Control Plane auth
  • Automatic Retries: Exponential backoff with configurable retry logic
  • Error Standardization: Converts errors to E11Error format
  • SSE Streaming: Server-Sent Events with RxJS Observables
  • IPC Client: Specialized client for service-to-service communication
  • Proxy Support: HTTP proxy configuration for restricted networks
  • Header Security: Automatic stripping of sensitive headers from errors
  • Type Safety: Full TypeScript generics for requests/responses

Main Components

RestClient

class RestClient {
  constructor(baseURL: string, options?: RestClientOptions)
 
  async get<Res>(endpoint: string, spec?: ReqSpec)
  async post<T, Res>(endpoint: string, spec?: BodyReqSpec<T>)
  async put<T, Res>(endpoint: string, spec?: BodyReqSpec<T>)
  async delete<Res>(endpoint: string, spec?: ReqSpec)
 
  listen<T>(endpoint: string, spec?: ReqSpec): {stream: Observable<T>, close: () => void}
 
  static rawRequest(): AxiosInstance
}

IPCClient

class IPCClient extends RestClient {
  static async fromServiceName(serviceName: string): Promise<IPCClient>
}

Automatically discovers service URLs and retrieves API keys from secrets.

RestClientOptions

{
  token?: string                          // Default bearer token
  onlyThrow500s?: boolean                 // Only throw on 5xx errors
  retries?: number                        // Retry attempts (default: 3)
  retryCondition?: (err) => boolean      // Custom retry logic
  httpsAgent?: any                        // Proxy agent
}

Authentication

Multi-Strategy Support

  • Bearer Token: Via token option or spec.auth.token
  • Tenant ID: Via spec.auth.tenantId header
  • API Key: IPCClient retrieves from secrets
  • GCP OIDC: Automatic service-to-service tokens (Cloud Run)
  • Control Plane: Platform-specific auth tokens

Auth Providers

  • GCPAuthProvider: Google Auth Library for Cloud Run
  • ControlPlaneAuthProvider: Control Plane environment tokens
  • AuthFactory: Automatic provider selection

Error Handling

Error Types

  • HTTP_ERROR: 4xx/5xx responses
  • NO_RESPONSE: Connection but no response
  • REQUEST_PROBLEM: Request setup error
  • NOT_AXIOS_ERROR: Non-Axios errors

Type Guards

isRestClientError(err)
isE11RestClientError(err)
isRestClientErrorWithCode(err, code)
e11RestClientErrorToE11Error(err)

Server-Sent Events

const {stream, close} = await client.listen<EventData>('/events')
 
stream.subscribe({
  next: (event) => handleEvent(event),
  error: (err) => handleError(err),
  complete: () => cleanup()
})
 
// Clean up when done
close()

Common Use Cases

  • Microservice-to-microservice communication
  • Third-party API integration
  • Real-time event streaming (SSE)
  • Authenticated API calls
  • Resilient HTTP communication with retries
  • Service discovery in Cloud Run/Control Plane

What Customers Don’t Have to Build

  • HTTP client configuration
  • Retry logic with exponential backoff
  • Multi-strategy authentication
  • Service-to-service auth token management
  • Error standardization
  • Header security (sensitive data filtering)
  • SSE streaming with RxJS
  • Service URL discovery
  • Proxy configuration
  • API key retrieval from secrets
Last updated on
RESTREST GCP