# superclient

> Create a fluent interface to an API

Latest version **1.4.3** (published 2016-03-10) · MIT license · 0 weekly downloads

## Install

```sh
npm install superclient
pnpm add superclient
yarn add superclient
bun add superclient
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.4.3 |
| Published | 2016-03-10 |
| First published | 2015-05-28 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 3 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1 |
| Author | Doug Moscrop |
| Maintainers | dmoscrop |
| Keywords | supertest, superagent, api, client |

## Links

- npm: https://www.npmjs.com/package/superclient
- Repository: https://github.com/dougmoscrop/superclient
- Homepage: https://github.com/dougmoscrop/superclient#readme
- Issues: https://github.com/dougmoscrop/superclient/issues
- npm.io page: https://npm.io/package/superclient

## Dependencies (3)

- [url](https://npm.io/package/url.md) 0.11.0
- [methods](https://npm.io/package/methods.md) 1.1.2
- [url-join](https://npm.io/package/url-join.md) 0.0.1

## Alternatives

- [launchdarkly-js-client-sdk](https://npm.io/package/launchdarkly-js-client-sdk.md) — 2.5M weekly downloads
- [@elastic/elasticsearch](https://npm.io/package/@elastic/elasticsearch.md) — 2.1M weekly downloads
- [@c8y/client](https://npm.io/package/@c8y/client.md) — 15.3K weekly downloads
- [@signaldb/maverickjs](https://npm.io/package/@signaldb/maverickjs.md) — 1.7K weekly downloads
- [@bbc/http-transport-cache](https://npm.io/package/@bbc/http-transport-cache.md) — 1.2K weekly downloads

## Recent versions

- 1.4.3 (latest) — 2016-03-10
- 1.4.2 — 2016-03-09
- 1.4.1 — 2016-03-08
- 1.4.0 — 2016-03-08
- 1.3.0 — 2015-06-01
- 1.2.0 — 2015-05-30
- 1.0.1 — 2015-05-29
- 1.0.0 — 2015-05-28

## README

# superclient
using it is pretty easy:
### configure routing

```javascript
    var superclient = require('superclient');
    
    // create a constructor by configuring the routing
    var Client = superclient(function() {
        // adds a basic route '/test'
        this.route('test');
        
        // adds a resource route '/images' and '/images/:id'
        this.resource('images');
        
        // add another resource route '/users' and '/users/:id'
        this.resource('users', function() {
            // this adds a sub-route `/users/:id/profile`
            this.route('profile');
        });
    });
```

`Client` is a constructor that takes an optional prefix and a function which is called for every request. This is how you can delegate to supertest or superagent.

```javascript
    // prefix all URLs with 'api'
    var api = new Client('api', function performRequest(verb, url) {
        return superagent[verb](url); // superagent(express)[verb](url)
    });
```

Now this `api` object is a fluent interface to the routing that was configured previously:

```javascript
    // remember we specified the prefix 'api'
    api.foo // undefined
    api.test // a 'handler' which has HTTP verbs on it
    api.test.get() // superagent.get(/api/test)
    
    // the call goes through to super[agent|test] like normal
    api.users.post().send({ name: 'new user' }); // superagent.post(/api/users)
    
    api.users(123).put() // superagent.put(/users/123)
    api.users(123).profile.get() // superagent.get(/users/123/profile)
```

The configuration step can be done separately and even exported as it's own package - since the request handling is provided late, you can use it as a real API client as well as for testing said API itself. Also since the prefix is determined outside of the routing structure this can come in handy (service location, etc.)

## things to add:
it would be interesting to support arbitrarily nested routing, including subresources i.e. `/foo/:foo_id/someRoute/bar/:bar_id`

it might also be ineresting to take a URL as a 'step' to build from, so if you get a Created response with a Location header, something like:

```javascript
    api.users.post({ /* ... */ }).then(function() {
        var location = '/users/9000'; // assume that's the header
        var user = api.users(/* undefined id */).url(location) // 'set' the url up to this point
        user.profile.get() // GET /users/9000/profile
    })
```

---
_Source: https://npm.io/package/superclient · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._