Skip to content

PAPI🔗

Abstract

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

NPM Version NPM Type Definitions npm bundle size (scoped) NPM Unpacked Size NPM License

Installation🔗

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

Node projects can install PAPI as a dependency:

npm install @studiokeywi/papi

Bun projects can install PAPI as a dependency:

bun add @studiokeywi/papi

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';

Tip

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 runtime implementation of the Web API fetch method

Danger

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

1
2
3
4
5
6
7
import { papi } from '@studiokeywi/papi';

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

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:

Albums endpoint from JSONPlaceholder

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:

Calling endpoints

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!

PAPI Docs
PAPI NPMJS
PAPI Repo