@spa-tools/api-client

@spa-tools

API Client

The @spa-tools/api-client package excels in calling HTTP API endpoints with features specifically designed for modern, data-driven web applications.

If your SPA has data workflows requiring calls to backend APIs (public and/or private), then this tool may be just what the doctor ordered.

Feature highlights include:

• Throttling
• Caching
• State Interpolation
• Result Mapping
• React (or not)
• TypeScript First
• Zero Dependencies
• Tree-shakable

Quickstart

It's highly advised to first checkout the @spa-tools documentation site for a complete list of features, usage scenarios, guidance, and reference.

Installation

npm install @spa-tools/api-client

Usage

import { callEndpoint } from '@spa-tools/api-client';

// define our data shape
export interface AlbumPhoto {
  albumId: number;
  id: number;
  title: string;
  url: string;
  thumbnailUrl: string;
}

// an engineer-friendly function to retrieve photos by album ID
export async function getAlbumPhotos(albumId: number) {
  //
  // the callEndpoint function is very similar to the fetch API but
  // with a variety of powerful features for request and response
  // (see Reference and Guides for more info).
  //
  // notice that we're specifying an array of AlbumPhoto objects
  // as the expected result data type which will give us very nice
  // intellisense when accessing the returned data; we could also
  // specify a custom error type as well if we wanted to
  const result = await callEndpoint<AlbumPhoto[]>(
    // we use an endpoint template here with a path param
    // which will auto-interpolate using the passed-in state
    'https://jsonplaceholder.typicode.com/albums/:albumId/photos',
    // this second argument contains the object we want to use to inject
    // state into the URL and as long as the state property names match
    // the path param names, they will auto-interpolate
    { albumId }
  );

  return result;
}

const albumId = 1;
const result = await getAlbumPhotos(albumId);

// the API Client calls always return a standardized result envelope
// that includes a data and an error property; while this structure
// cannot be changed, the interfaces of the underlying data and error
// types are 100% up to you and your API
if (result.data) {
  console.log(`Photos for album with ID "${albumId}":`);
  console.log(result.data);
} else if (result.error) {
  console.error(`Error retrieving photos for album with ID "${albumId}":`);
  console.error(result.error);
}

Docsite

View the @spa-tools documentation site for complete reference.

Contributing

If you're interested in contributing to @spa-tools, please first create an issue on the @spa-tools monorepo in GitHub or comment on an already open issue. From there we can discuss the feature or bugfix you're interested in and how best to approach it.

Unit Test Coverage

All packages in @spa-tools require 100% unit test coverage. This is a condition for all PRs to be merged whether you're adding a new feature or fixing a bug.

License

All packages in @spa-tools are licensed under the MIT license. Copyright © 2024, Ryan Howard (rollercodester). All rights reserved.