# stallion

> Simple way to create clients for your REST based services in Node

Latest version **0.4.5** (published 2015-08-06) · MIT license · 0 weekly downloads

## Install

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

## Health

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

Positive: no vulnerabilities.

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

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.4.5 |
| Published | 2015-08-06 |
| First published | 2015-06-29 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 2 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 4 |
| Author | Ryan Hubbard |
| Maintainers | hubmo |
| Keywords | rest, client, api, wrapper, service |

## Links

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

## Dependencies (2)

- [restler](https://npm.io/package/restler.md) prusik/restler#trimJsonData
- [pluralize](https://npm.io/package/pluralize.md) ^1.1.2

## 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

- 0.4.5 (latest) — 2015-08-06
- 0.4.4 — 2015-07-14
- 0.4.3 — 2015-07-13
- 0.4.2 — 2015-07-13
- 0.1.0 — 2015-06-29

## README

# Stallion [![Build](https://img.shields.io/codeship/faaed070-00df-0133-d340-46d3771abf46.svg)]()
> Simple, lightweight way to create promise based Node clients for REST services

Would love some feedback, including how to make the README better. Drop me an email, or create an issue or PR.


Licensed under the MIT-LICENSE

## Readme Todos
1. How authorization works
2. Everything is promise based
3. Get,Delete & Query strings
4. Customer functions & resolving



## Installing
`npm install stallion --save`

## Testing
`npm test` or `gulp test`

You can use `gulp watch` which will run tests on file changes


## Creating a client

Creating a client is simple. Just delcare the objects

```javascript
// Create the API client
//----------------------------------
var config = {
  baseUrl: 'https://api.service.com',
  objects: {
    // Using shortcut declartion for Create, Read, Update & Delete
    User: 'crud',

    // Full object declartion
    Task: {
      actions: 'crud',
      start: function(id) {
        return this.put(`tasks/${id}/start`);
      }
    }
  }
};

var SomeRestApi = new Stallion(config);


// Later, you can create & use an api client instance
//---------------------------------------------------
var api = new SomeRestApi('user', 'pass');

api.createUser({email: 'john.wick@xyz.com'})
.then( user => {
  // Do something with the user
  console.log(user);
})
.catch(e => {
  console.log(e);
});
```

This will create the following methods for Task on the service:

* createTask
* updateTask
* getTask
* deleteTask
* startTask

**NOTE**: May change the configuration before 1.0 release

## Actions
Stallion builds in the common calls REST services for resources: Create, Read, Update (both Put & Patch), and Delete and makes it really easy for you to add them in 2 ways using the objects option in the config:

* Shortcut declaration
```javascript
{
  User: 'crudpl'
}
```

* Using the `action` property on the object description
```javascript
{
  User: {
    actions: 'crudpl'
  }
}
```

There are 5 actions that are available:

* `c` Create: adds a `create<Object>(data)` method which POST's the data to /:objects
* `r` Read: adds a `get<Object>(id)` method which GET's to /:objects/:id
* `u` Update: adds `update<Object>(data)` method which PUT's the param to the service /:objects/:data.id
* `d` Delete: adds `delete<Object>(id)` method which DELETE's to /:objects/:id
* `p` Patch: adds `patch<Object>(data)` method which PATCH's the param to the service /:objects/:data.id
* `l` List: adds a `get<Objects>(query)` method (notice it's plural) which GET's to /:objects but the query object will be translated to a query string

## Custom methods
You can add custom methods to an object by simply adding the function to the objects definition.

```javascript
{
  Lead: {
    convert: function(id) {
      return this.post('lead/' + id + '/convert');
    }
  }
}
```

This will create a `convertLead(id)` method on the service. The provided function will be called in the context of a [Restler](https://github.com/danwrong/restler) client, so you can use any method available that Rester exposes.

## Todos / Thoughts / Comments
1. Convert to full ES6 (originally written in native iojs ES6), now it's transpiled so anyone can use it
2. Add verion (specify header value)
3. Custom function for mapping from Action to HTTP calls
4. Paging
5. Additional authorization options
6. Before / After hooks
7. Exposing array of api methods
8. Shorthand for custom actions
9. Expose request & response objects
10. Add option to create 'client.createResource' vs 'client.resource.create'
11. Wrap Rester's default action method (post, get, etc) to make it easier to send the body & query params
12. Upsert mode - Some API's use POST for create & update. In this case for all updates you need to create a custom update function so would be nice to have way to handle this automatically (1. All updates, 2. single resources)

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