Apisauce is a library that simplifies the process of making HTTP requests in JavaScript applications. It is built on top of the popular axios library and provides a cleaner and more intuitive API for handling API requests and responses.
Creating an API instance
This feature allows you to create an API instance with a base URL and default headers. This instance can then be used to make various HTTP requests.
const { create } = require('apisauce');
const api = create({
baseURL: 'https://api.example.com',
headers: { Accept: 'application/json' },
});Making GET requests
This feature allows you to make GET requests to the specified endpoint. The response object contains useful information such as the data, status, and any problems encountered.
api.get('/users').then(response => {
if (response.ok) {
console.log(response.data);
} else {
console.error(response.problem);
}
});Making POST requests
This feature allows you to make POST requests with a payload. The response object can be used to handle the result of the request.
api.post('/users', { name: 'John Doe', email: 'john.doe@example.com' }).then(response => {
if (response.ok) {
console.log(response.data);
} else {
console.error(response.problem);
}
});Setting request and response transforms
This feature allows you to add transforms to requests and responses. Request transforms can modify the request before it is sent, and response transforms can modify the response before it is processed.
api.addRequestTransform(request => {
request.headers['Authorization'] = 'Bearer token';
});
api.addResponseTransform(response => {
if (!response.ok) {
response.data = { error: 'Something went wrong' };
}
});Axios is a promise-based HTTP client for the browser and Node.js. It is the underlying library that apisauce is built on top of. While axios provides a more general-purpose API, apisauce offers a more streamlined and opinionated interface for making API requests.
Fetch is a built-in JavaScript API for making HTTP requests. It is more low-level compared to apisauce and does not include features like request/response transforms or built-in error handling. Apisauce provides a higher-level abstraction with additional features.
Superagent is a small, progressive client-side HTTP request library. It provides a flexible API for making HTTP requests but does not include some of the higher-level features that apisauce offers, such as request/response transforms and built-in error handling.
(Ring ring ring)
< Hello?
> Hi, can I speak to JSON API.
< Speaking.
> Hi, it's me JavaScript. Look, we need to talk.
< Now is not a good time...
> Wait, I just wanted to say, sorry.
< ...
Talking to APIs doesn't have to be awkward anymore.
axios http client libraryproblem property to help guide exception flownpm i apisauce --save
axios@^0.18.0.// showLastCommitMessageForThisLibrary.js
import {create} from 'apisauce'
// define the api
const api = create({
baseURL: 'https://api.github.com',
headers: {'Accept': 'application/vnd.github.v3+json'}
})
// start making calls
api
.get('/repos/skellock/apisauce/commits')
.then((response) => response.data[0].commit.message)
.then(console.log)
// customizing headers per-request
api.post('/users', {name: 'steve'}, {headers: {'x-gigawatts': '1.21'}})
See the examples folder for more code.
You create an api by calling .create() and passing in a configuration object.
const api = create({baseURL: 'https://api.github.com'})
The only required property is baseURL and it should be the starting point for
your API. It can contain a sub-path and a port as well.
const api = create({baseURL: 'https://example.com/api/v3'})
HTTP request headers for all requests can be included as well.
const api = create({
baseURL: '...',
headers: {
'X-API-KEY': '123',
'X-MARKS-THE-SPOT': 'yarrrrr'
}
})
Default timeouts can be applied too:
const api = create({baseURL: '...', timeout: 30000}) // 30 seconds
With your fresh api, you can now call it like this:
api.get('/repos/skellock/apisauce/commits')
api.head('/me')
api.delete('/users/69')
api.post('/todos', {note: 'jump around'}, {headers: {'x-ray': 'machine'}})
api.patch('/servers/1', {live: false})
api.put('/servers/1', {live: true})
api.link('/images/my_dog.jpg', {}, {headers: {Link: '<http://example.com/profiles/joe>; rel="tag"'}})
api.unlink('/images/my_dog.jpg', {}, {headers: {Link: '<http://example.com/profiles/joe>; rel="tag"'}})
get, head, delete, link and unlink accept 3 parameters:
axios request (optional)post, put, and patch accept 3 different parameters:
axios request (optional)The responses are promise-based, so you'll need to handle things in a
.then() function.
The promised is always resolved with a response object.
Even if there was a problem with the request! This is one of the goals of
this library. It ensures sane calling code without having to handle .catch
and have 2 separate flows.
A response will always have these 2 properties:
ok - Boolean - True is the status code is in the 200's; false otherwise.
problem - String - One of 6 different values (see below - problem codes)
If the request made it to the server and got a response of any kind, response will also have these properties:
data - Object - this is probably the thing you're after.
status - Number - the HTTP response code
headers - Object - the HTTP response headers
config - Object - the `axios` config object used to make the request
duration - Number - the number of milliseconds it took to run this request
Sometimes on different platforms you need access to the original axios error that was thrown:
originalError - Error - the error that axios threw in case you need more info
You can change the URL your api is connecting to.
api.setBaseURL('https://some.other.place.com/api/v100')
console.log(`omg i am now at ${api.getBaseURL()}`)
Once you've created your api, you're able to change HTTP requests by
calling setHeader or setHeaders on the api. These stay with the api instance, so you can just set 'em and forget 'em.
api.setHeader('Authorization', 'the new token goes here')
api.setHeaders({
'Authorization': 'token',
'X-Even-More': 'hawtness'
})
Monitors are functions you can attach to the API which will be called when any request is made. You can use it to do things like:
Monitors are run just before the promise is resolved. You get an early sneak peak at what will come back.
You cannot change anything, just look.
Here's a sample monitor:
const naviMonitor = (response) => console.log('hey! listen! ', response)
api.addMonitor(naviMonitor)
Any exceptions that you trigger in your monitor will not affect the flow of the api request.
api.addMonitor(response => this.kaboom())
Internally, each monitor callback is surrounded by an oppressive try/catch
block.
Remember. Safety first!
In addition to monitoring, you can change every request or response globally.
This can be useful if you would like to:
Unlike monitors, exceptions are not swallowed. They will bring down the stack, so careful!
For responses, you're provided an object with these properties.
data - the object originally from the server that you might wanna mess withduration - the number of millisecondsproblem - the problem code (see the bottom for the list)ok - true or falsestatus - the HTTP status codeheaders - the HTTP response headersconfig - the underlying axios config for the requestData is the only option changeable.
api.addResponseTransform(response => {
const badluck = Math.floor(Math.random() * 10) === 0
if (badluck) {
// just mutate the data to what you want.
response.data.doorsOpen = false
response.data.message = 'I cannot let you do that.'
}
})
For requests, you are given a request object. Mutate anything in here to change anything about the request.
The object passed in has these properties:
data - the object being passed up to the servermethod - the HTTP verburl - the url we're hittingheaders - the request headersparams - the request params for get, delete, head, link, unlinkRequest transforms can be a function:
api.addRequestTransform(request => {
request.headers['X-Request-Transform'] = 'Changing Stuff!'
request.params['page'] = 42
delete request.params.secure
request.url = request.url.replace(/\/v1\//, '/v2/')
if (request.data.password && request.data.password === 'password') {
request.data.username = `${request.data.username} is secure!`
}
})
And you can also add an async version for use with Promises or async/await. When you resolve
your promise, ensure you pass the request along.
api.addAsyncRequestTransform(request => {
return new Promise(resolve => setTimeout(resolve, 2000))
})
api.addAsyncRequestTransform(request => async () => {
await AsyncStorage.load('something')
})
This is great if you need to fetch an API key from storage for example.
Multiple async transforms will be run one at a time in succession, not parallel.
If you're more of a stage-0 kinda person, you can use it like this:
const api = create({baseURL: '...'})
const response = await api.get('/slowest/site/on/the/net')
console.log(response.ok) // yay!
The problem property on responses is filled with the best
guess on where the problem lies. You can use a switch to
check the problem. The values are exposed as CONSTANTS
hanging on your built API.
Constant VALUE Status Code Explanation
----------------------------------------------------------------------------------------
NONE null 200-299 No problems.
CLIENT_ERROR 'CLIENT_ERROR' 400-499 Any non-specific 400 series error.
SERVER_ERROR 'SERVER_ERROR' 500-599 Any 500 series error.
TIMEOUT_ERROR 'TIMEOUT_ERROR' --- Server didn't respond in time.
CONNECTION_ERROR 'CONNECTION_ERROR' --- Server not available, bad dns.
NETWORK_ERROR 'NETWORK_ERROR' --- Network not available.
CANCEL_ERROR 'CANCEL_ERROR' --- Request has been cancelled. Only possible if `cancelToken` is provided in config, see axios `Cancellation`.
Which problem is chosen will be picked by walking down the list.
Bugs? Comments? Features? PRs and Issues happily welcomed!
deleteHeader(). #95 by @jkeambabel-plugin-ramda for lighter builds. #93 by @DiscoStarslayerprettier and standard --fix. #98 by @skellockdist script to repackage. :( Failsauce.FAQs
Axios + standardized errors + request/response transforms.
The npm package apisauce receives a total of 53,954 weekly downloads. As such, apisauce popularity was classified as popular.
We found that apisauce demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
Socket's threat research team has detected five malicious npm packages targeting Roblox developers, deploying malware to steal credentials and personal data.
Security News
vlt introduced its new package manager and a serverless registry this week, innovating in a space where npm has stagnated.
Security News
Research
The Socket Research Team uncovered a malicious Python package typosquatting the popular 'fabric' SSH library, silently exfiltrating AWS credentials from unsuspecting developers.