PAPI

The Proxy API tool from studioKeywi for better DX. Zero dependencies. Built with ❤️ and Bun, Material for MkDocs, TypeDoc, and Vitest

Installation

PAPI is available to install through the NPM registry and can be installed by any runtime that is compatible with NPM installs:

Node

Node projects can install PAPI as a dependency:

npm install @studiokeywi/papi

Bun

Bun projects can install PAPI as a dependency:

bun add @studiokeywi/papi

Deno

Deno projects can import PAPI using the npm: specifier:

import { papi } from 'npm:@studiokeywi/papi';

Or by adding to the import map of deno.json:

{
  "imports": {
    "papi": "npm:@studiokeywi/papi"
  }
}

import { papi } from 'papi';

PAPI is a TypeScript first implementation. Along with providing and exporting its own types, exports are provided for the Bun and Deno runtimes as well as an explicit @studiokeywi/papi/ts export entry

Under the hood, PAPI is a simple builder syntax combined with a custom JS Proxy object used to wrap around the Web API fetch method

PAPI performs no validation on API responses, nor does PAPI provide any integrated security features. When building an API caller, PAPI allows an API key/token value to be provided automatically in the Authorization header in Bearer: [token] format in plaintext. This could be detected by any software that can read or intercept network requests

Beyond this, PAPI allows any standard option that can be provided to the second argument of your runtime's implementation of the Web API fetch method. If you are concerned about the security/validity of your network calls, we strongly suggest utilizing other libraries in addition to/instead of PAPI to perform your security/validation

Usage

PAPI is designed with a chainable builder approach to defining the shape of any API, combined with a chained property approach to calling the various API endpoints. The combination allows for a natural and expressive way to declare and request expected API responses

PAPI in 4 lines

import { papi } from '@studiokeywi/papi';

const url = 'https://jsonplaceholder.typicode.com';
const albumShape = { userId: 0, id: 0, title: '' };
const allAlbums = await papi(url)                     /* 1. Define a base URL */
  .path('albums', albums => albums.get([albumShape])) /* 2. Define API endpoints */
  .build()                                            /* 3. Create API caller */
  .albums.get();                                      /* 4. Make an API request */
// typeof allAlbums = { userId: number; id: number; title: string }[]

API Builder

PAPI allows API endpoints to be defined as simply or robustly as needed. An expanded example of the JSONPlaceholder API's /albums endpoint is demonstrated below:

Example Endpoint

import { papi } from '@studiokeywi/papi';

const albumShape = { userId: 0, id: 0, title: '' };
const errShape = {};
const photoShape = { albumId: 0, id: 0, title: '', url: '', thumbnailUrl: '' };

const apiCaller = papi('https://jsonplaceholder.typicode.com')
  .path('albums', $albums =>
    $albums
      .get([albumShape], $get => $get.error(errShape).queryOpt(albumShape))
      .post(albumShape, $post => $post.bodyOpt(albumShape).error(errShape))
      .slug($albumId =>
        $albumId
          .get(albumShape, $get => $get.error(errShape))
          .delete({}, $del => $del.error(errShape))
          .patch(albumShape, $patch => $patch.bodyOpt(albumShape).error(errShape))
          .put(albumShape, $put => $put.bodyOpt(albumShape).error(errShape))
          .path('photos', $photos => $photos.get([photoShape], $get => $get.error(errShape)))
      )
  )
  .build();

See the builder docs for more

API Caller

The API Caller tool allows arbitrary API endpoints to be called. Following from the example above:

Example Caller

const data = { title: "studioKeywi's Loudest Hits!" };
const newAlbum = await apiCaller.albums.post({ data });
if (!('id' in newAlbum)) throw new Error(`API Post failed and returned ${newAlbum}`);

const photos = await apiCaller.albums[newAlbum.id].photos.get();
if (!('length' in photos)) throw new Error(`API Get failed and returned ${photos}`);

photos.forEach(photo => {
  // ...
});

See the caller docs for more

API Documentation

Generated by TypeDoc: API Documentation

Future

Think PAPI is missing a feature? Open an issue!

Links

PAPI Docs
PAPI NPMJS
PAPI Repo