RETCHful is three simple functions that make doing RESTful calls more reliable and enjoyable than using fetch
directly. It works on both client and server.
retch.get(url[, options])
Sends an HTTP GET
for all resources. Get a specific resource by setting the id
option. Optionally attach query params by setting query
in options.
retch.save(url[, options])
Sends an HTTP POST
if there is no id. If there is an id, then it'll PUT
. If id has a different name configure it using the altId
option.
retch.delete(url, {id})
Sends an HTTP DELETE
. You must include the id option.
url
A string. Do not include the id of the resource; it will be taken from options
. Ending with or without "/" is okay.
options
Pass-through to fetch's init arg with a few things to be aware of:
body
is stringified for you.method
is set based on the function used (see above).query
(RETCHful only) Key-value object added non-destructively tourl
as a query string. Primarily forget
, but works with all.id
(RETCHful only) A number or string. If present, will be appended tourl
. Required bydelete
and used byget
to fetch a single resource rather than all.save
ignores this and instead looks atbody
for the id of the resource (seealtId
for more info).altId
(RETCHful only) Specify an alternative name for the id property ofbody
. Save uses this name or defaults tobody.id
.
Notes
The get, save, and delete functions ultimately call fetch and return the Promise from response.json()
. Internally response.ok
is checked for you and if not ok the Promise is rejected. Also, the default values used for init can be seen here: https://github.com/jfbrennan/retch/blob/master/index.js#L34
Examples
// Require it server-side or use the `retch` global in the browser
const retch = require('retchful');
// Todos endpoint
const url = 'https://jsonplaceholder.typicode.com/todos';
// Fetch all todos
// GET https://jsonplaceholder.typicode.com/todos
retch.get(url)
.then(data => console.log(data))
// Fetch todos with query params
// GET https://jsonplaceholder.typicode.com/todos?completed=false
retch.get(url, {query: {completed: false}})
.then(data => console.log(data))
// Fetch a specific todo
// GET https://jsonplaceholder.typicode.com/todos/1
retch.get(url, {id: '1'})
.then(data => console.log(data))
// Save a new todo
// POST https://jsonplaceholder.typicode.com/todos
retch.save(url, {body: {title: 'Foo', body: 'Bar'}})
.then(data => console.log(data))
// Save changes to an existing todo
// PUT https://jsonplaceholder.typicode.com/todos/1
retch.save(url, {body: {id: '1', title: 'Foo', body: 'Baz'}})
.then(data => console.log(data))
// Save changes to todo when id is not named "id"
// PUT https://jsonplaceholder.typicode.com/todos/1
retch.save(url, {altId: 'todo_id', body: {todo_id: '1', title: 'Foo', body: 'Baz'}})
.then(data => console.log(data))
// Delete a todo
// DELETE https://jsonplaceholder.typicode.com/todos/1
retch.delete(url, {id: '1'})
.then(data => console.log(data))
CDN
https://unpkg.com/retchful@1.0.0-beta/dist/min.js
Then just use the global retch.get|save|delete
functions. Too easy.
Note that RETCHful makes use of fetch, Promise, URL, and URLSearchParams.append, so you may need to polyfill for older browsers. The excellent polyfill.io service is a really smart way to go.
NPM
npm install retchful
const retch = require('retchful')
Note that retch makes use of fetch, which needs to be installed for Node. The node-fetch module is recommended.
Fetch is a low level API, so it gets ugly when used directly. I took some inspiration from Backbone which imo is one of the most developer-friendly libraries ever. It's still the best when working with lots of a RESTful APIs, so retch attempts to give you some of that goodness.