ngx-api-client

Project Overview

Angular's HttpClient gives you a request; it does not give you a policy. Where the base URL comes from, how a failed response becomes something a component can render, which requests are safe to retry, and how a global progress bar learns anything is in flight — every application answers those four questions inside an ApiService that grows until nobody wants to touch it. ngx-api-client is that service, extracted after the fourth rewrite and made configurable: versioning as a pluggable strategy instead of string concatenation, one ApiError shape regardless of what the backend returns, retry that respects idempotency and Retry-After, and presentation left entirely to the application. Published on npm as @ismailza/ngx-api-client with a Docusaurus documentation site and a CI matrix that validates the packed tarball against every supported Angular major.

Features

• ✓Configurable versioning — URL segment, query parameter, header, or media type, overridable per request or disabled entirely
• ✓RFC 9457 problem+json errors normalized into a single ApiError shape, whether the backend sends problem details, a plain-text proxy page, or nothing at all
• ✓Retry with exponential backoff and jitter — honours Retry-After, skips non-idempotent methods by default
• ✓Per-request options carried through HttpContext rather than mutable service state, so concurrent calls never interfere
• ✓Pluggable ApiErrorHandler and ApiSuccessHandler — the library never renders anything
• ✓Loading state as a counted signal, so concurrent requests don't flicker the progress bar off early
• ✓Typed pagination helper (getPage) returning a PaginatedResponse<T>
• ✓No UI dependency — peers are @angular/core, @angular/common, and rxjs, nothing else

Challenges

• •Knowing which parts of a copy-pasted service genuinely varied between projects, and which had only ever looked variable
• •Supporting backends that version by URL, header, query parameter, media type, or release date — without leaking that choice into application code
• •Presenting one error contract to components when failures arrive as problem+json, plain-text proxy errors, or a network drop with status 0
• •Deciding how much the library should do for the consumer, particularly around interceptor registration and error presentation
• •Backing the declared Angular peer dependency range with evidence rather than assumption

Solution

Extracted only after the fourth reimplementation, so the configuration surface reflects variation observed in real projects instead of anticipated. Versioning became a strategy object rather than string concatenation, and version accepts strings as well as numbers for date-based schemes. Every failure is normalized into one ApiError carrying a machine-readable code and a traceId that falls back to the X-Trace-Id header. Interceptors are registered by the consumer rather than auto-injected, because ordering relative to an auth interceptor is a decision only the application can make. CI installs the packed tarball into a throwaway consumer app per Angular major and runs type-check, production build, and a runtime injector test.

Architecture

A provider function (provideApi) supplies configuration through injection tokens. ApiService resolves the URL — baseUrl + optional prefix + optional version segment + endpoint — and attaches per-request options to HttpContext. Three standalone functional interceptors read that context: apiErrorInterceptor normalizes failures into ApiError, apiSuccessInterceptor dispatches success messages, retryInterceptor applies backoff to retryable statuses. Handlers are abstract classes the application overrides via DI, keeping presentation out of the HTTP layer. Built with ng-packagr into an Angular Package Format distributable.

Results & Impact

• ✓Published to npm as @ismailza/ngx-api-client under MIT, with releases automated by release-please
• ✓Every supported Angular version validated in CI on each push, against the packaged npm artifact rather than the source — the declared peer range is a tested claim, not an assumption
• ✓118 unit tests across the service, interceptors, handlers, and provider
• ✓Full documentation site at ismailza.github.io/ngx-api-client, deployed from CI
• ✓Zero runtime dependencies beyond tslib; nothing pulled into the consumer's bundle but the HTTP layer itself