Stallion
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
- How authorization works
- Everything is promise based
- Get,Delete & Query strings
- 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
// 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' { return this; } ; var SomeRestApi = config; // Later, you can create & use an api client instance//---------------------------------------------------var api = 'user' 'pass'; api;
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
User: 'crudpl'
- Using the
action
property on the object description
User: actions: 'crudpl'
There are 5 actions that are available:
c
Create: adds acreate<Object>(data)
method which POST's the data to /:objectsr
Read: adds aget<Object>(id)
method which GET's to /:objects/:idu
Update: addsupdate<Object>(data)
method which PUT's the param to the service /:objects/:data.idd
Delete: addsdelete<Object>(id)
method which DELETE's to /:objects/:idp
Patch: addspatch<Object>(data)
method which PATCH's the param to the service /:objects/:data.idl
List: adds aget<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.
Lead: { return this; }
This will create a convertLead(id)
method on the service. The provided function will be called in the context of a Restler client, so you can use any method available that Rester exposes.
Todos / Thoughts / Comments
- Convert to full ES6 (originally written in native iojs ES6), now it's transpiled so anyone can use it
- Add verion (specify header value)
- Custom function for mapping from Action to HTTP calls
- Paging
- Additional authorization options
- Before / After hooks
- Exposing array of api methods
- Shorthand for custom actions
- Expose request & response objects
- Add option to create 'client.createResource' vs 'client.resource.create'
- Wrap Rester's default action method (post, get, etc) to make it easier to send the body & query params
- 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)