superapi

library0.23.1jsnpmunverified

A wrapper around superagent that simplifies HTTP API calls by allowing developers to define services declaratively with methods, paths, and default options. The library provides a centralized configuration for base URL, headers, and options, and returns Promise-based functions for each service. Current version 0.23.1 is stable but has minimal release cadence (last update 2018). It differs from bare superagent by removing boilerplate and enabling service definitions, though it requires manual injection of the superagent agent and is not actively maintained. Superseded by modern alternatives like Axios or ky.

http-networking

npm install superapi

github ↗package ↗

INSTALL

IMPORT

SIG · SUPERAPI

superapi

http-networkingjavascriptv0.23.1

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default

✓ import superapi from 'superapi'

✗ const superapi = require('superapi')

The module exports a `default` function; in CommonJS, require returns the default function, but the correct import is the default export.

Superapi

✓ import superapi from 'superapi'

There is no named export; only default export.

api agent injection

✓ const api = superapi({...}); api.agent = require('superagent');

✗ const api = require('superapi').default({...}); api.agent = require('superagent');

When using CommonJS, require('superapi') returns the default function directly, so calling `.default` is unnecessary and will break.

Shows how to configure superapi with a base URL, headers, services, inject superagent, and make GET and POST calls using promises.

import superapi from 'superapi'; import superagent from 'superagent'; const api = superapi({ baseUrl: 'https://api.example.com', headers: { 'X-Requested-With': 'XMLHttpRequest' }, services: { getUsers: { path: '/users', method: 'GET' }, createUser: { path: '/users', method: 'POST', options: { type: 'json' } } } }); api.agent = superagent; // GET request api.api.getUsers({ params: { page: 1 } }) .then(response => console.log(response.body)) .catch(err => console.error(err)); // POST request api.api.createUser({ data: { name: 'John' } }) .then(response => console.log('Created')) .catch(err => console.error(err));

Debug

Known issues

gotchaMust assign `superagent` to `api.agent` after creating the instance; forgetting this will cause 'agent is undefined' errors.

fix

api.agent = require('superagent');

affects: all

breakingDirect use of api.get(), api.post(), etc. requires `api.agent` assignment; without it, those methods will throw.

fix

Check that api.agent is set before calling HTTP verb helpers.

affects: all

gotchaService path must start with '/' unless it is a relative path from baseUrl; misuse may result in incorrect URLs.

fix

Ensure service paths are absolute (with leading '/') or correctly relative.

affects: all

deprecatedThe library uses an outdated build system and doesn't support ESM natively; importing with ES syntax may fail in bundlers.

fix

Use CommonJS require() and ensure a bundler that can handle ES module transpiled code.

affects: 0.x

gotchaThe `superapi.default` export is the main function; in CommonJS, `require('superapi')` returns it directly, not an object with `default` property.

fix

Use `const superapi = require('superapi');` instead of `require('superapi').default`.

affects: 0.x

Errors

Common errors & fixes

TypeError: Cannot read properties of undefined (reading 'get')

api.agent is not set; HTTP verb helpers (api.get, api.post) are undefined.

fix

Add api.agent = require('superagent'); after creating the api instance.

UnhandledPromiseRejectionWarning: TypeError: api.api.getUsers is not a function

Service name in config does not match the call; spaces or case mismatch.

fix

Check the `services` configuration: the key used in `api.api[key]` must exactly match the key in the services object.

Error: cannot resolve path: /users

Service path is missing leading '/' or baseUrl is misconfigured.

fix

Ensure the path in service config starts with '/' and the baseUrl ends without a slash, or adjust accordingly.

Upgrade

Version history

0.23.1latest on npm

Audit

Dependencies

superagentrequiredRequired for HTTP requests; must be injected via `api.agent`

Agent activity

11 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/stephanebachelier/superapi ↗

packagehttps://www.npmjs.com/package/superapi ↗