A simple, lightweight & framework agnostic JSON:API client using Axios
Migration guide for v9 & previous major releases
| Package | Package Size* | Node | Chrome | Firefox | Safari | Edge |
|---|---|---|---|---|---|---|
kitsu | ≤ 8.2 kb | 10+ | 72+ | 78+ | 12.1+ | 86+ |
* Including all dependencies & minified with brotli
{
data: {
id: '1'
type: 'articles'
attributes: {
title: 'JSON API paints my bikeshed'
}
relationships: {
author: {
data: {
id: '42'
type: 'people'
}
}
}
}
included: [
{
id: '42'
type: 'people'
attributes: {
name: 'John'
}
}
]
}
{
data: {
id: '1'
type: 'articles'
title: 'JSON API paints my bikeshed'
author: {
data: {
id: '42'
type: 'people'
name: 'John'
}
}
}
}
yarn add kitsu
npm install kitsu
import Kitsu from 'kitsu' // ES Modules & Babel
const Kitsu = require('kitsu') // CommonJS & Browserify
// Kitsu.io's API
const api = new Kitsu()
// Other JSON:API servers
const api = new Kitsu({
baseURL: 'https://api.example/2'
})
// Using with async/await
const res = await api.get('anime')
// Using with Promises
api.get('anime')
.then(res => { ... })
.catch(err => { ... })
// Fetching resources (get/fetch)
api.fetch('anime')
api.fetch('anime', { filter: { id: 1 } })
api.fetch('anime/1/episodes')
api.fetch('anime/1/relationships/episodes')
// Creating resources (post/create)
api.create('post', {
content: 'some content'
})
// Updating resources (patch/update)
api.update('post', {
id: '1',
content: 'new content'
})
// Deleting resources (delete/remove)
api.remove('post', 1)
// JSON:API parameters
api.get('users', {
include: 'followers,waifu.character',
fields: {
users: 'slug,followers,waifu'
},
filter: {
slug: 'wopian'
},
sort: '-id',
page: {
limit: 5,
offset: 0
}
})
If you're working with Kitsu.io's API, their API docs lists all available resources with their attributes & relationships
packages/kitsu/src/index.js:30-473
Creates a new kitsu instance
options Object? Options (optional, default {})
options.baseURL string Set the API endpoint (optional, default https://kitsu.io/api/edge)options.headers Object? Additional headers to send with the requestsoptions.camelCaseTypes boolean If enabled, type will be converted to camelCase from kebab-casae or snake_case (optional, default true)options.resourceCase ("kebab" | "snake" | "none") Case to convert camelCase to. kebab - /library-entries; snake - /library_entries;none-/libraryEntries` (optional, default kebab)options.pluralize boolean If enabled, /user will become /users in the URL request and type will be pluralized in POST, PATCH and DELETE requests (optional, default true)options.timeout number Set the request timeout in milliseconds (optional, default 30000)options.axiosOptions Object? Additional options for the axios instance (see axios/axios#request-config for details)Using with Kitsu.io's API
const api = new Kitsu()
Using another API server
const api = new Kitsu({
baseURL: 'https://api.example.org/2'
})
Setting headers
const api = new Kitsu({
headers: {
'User-Agent': 'MyApp/1.0.0 (github.com/username/repo)',
Authorization: 'Bearer 1234567890'
}
})
packages/kitsu/src/index.js:52-53
If pluralization is enabled (default, see Kitsu constructor docs) then pluralization rules can be added
Adding an uncountable pluralization rule
api.plural.plural('paper') //=> 'papers'
api.plural.addUncountableRule('paper')
api.plural.plural('paper') //=> 'paper'
packages/kitsu/src/index.js:67-67
Get the current headers or add additional headers
Get all headers
api.headers
Get a single header's value
api.headers['User-Agent']
Add or update a header's value
api.headers['Authorization'] = 'Bearer 1234567890'
Returns Object All the current headers
packages/kitsu/src/index.js:112-112
Axios Interceptors (alias of axios.interceptors)
You can intercept responses before they are handled by get, post, patch and delete and before requests are sent to the API server.
Request Interceptor
// Add a request interceptor
api.interceptors.request.use(config => {
// Do something before request is sent
return config
}, error => {
// Do something with the request error
return Promise.reject(error)
})
Response Interceptor
// Add a response interceptor
api.interceptors.response.use(response => {
// Any status code that lie within the range of 2xx cause this function to trigger
// Do something with response data
return response
}, error => {
// Any status codes that falls outside the range of 2xx cause this function to trigger
// Do something with response error
return Promise.reject(error)
})
Removing Interceptors
const myInterceptor = api.interceptors.request.use(function () {...})
api.interceptors.request.eject(myInterceptor)
packages/kitsu/src/index.js:198-217
Fetch resources (alias fetch)
model string Resource to fetch data from. Expected formats are :resource, :resource/:id, :resource/:id/:relationship or :resource/:id/relationships/:relationshipparams Object? JSON-API request queries. Any JSON:API query parameter not mentioned below is supported out of the box. (optional, default {})
params.page Object? JSON:API Pagination. All pagination strategies are supported, even if they are not listed below.
params.page.limit number? Number of resources to return in request (Offset-based) - Note: For Kitsu.io, max is 20 except on libraryEntries which has a max of 500params.page.offset number? Number of resources to offset the dataset by (Offset-based)params.page.number number? Page of resources to return in request (Page-based) - Note: Not supported on Kitsu.ioparams.page.size number? Number of resources to return in request (Page-based and cursor-based) - Note: Not supported on Kitsu.ioparams.page.before string? Get the previous page of resources (Cursor-based) - Note: Not Supported on Kitsu.ioparams.page.after string? Get the next page of resources (Cursor-based) - Note: Not Supported on Kitsu.ioparams.fields Object? Return a sparse fieldset with only the included attributes/relationships - JSON:API Sparse Fieldsetsparams.filter Object? Filter dataset by attribute values - JSON:API Filteringparams.sort string? Sort dataset by one or more comma separated attributes (prepend - for descending order) - JSON:API Sortingparams.include string? Include relationship data - JSON:API Includesheaders Object? Additional headers to send with the request (optional, default {})Getting a resource with JSON:API parameters
api.get('users', {
fields: {
users: 'name,birthday'
},
filter: {
name: 'wopian'
}
})
Getting a collection of resources with their relationships
api.get('anime', {
include: 'categories'
})
Getting a single resource by ID (method one)
api.get('anime/2', {
include: 'categories'
})
Getting a single resource by ID (method two)
api.get('anime', {
include: 'categories',
filter: { id: '2' }
})
Getting a resource's relationship data only
api.get('anime/2/categories')
Getting a resource with nested JSON:API filters (not supported by Kitsu.io's API)
// resource?filter[x][y]=value
api.get('resource', {
filter: {
x: {
y: 'value'
}
}
}
Handling errors (async/await)
try {
const { data } = await api.get('anime')
} catch (err) {
// Array of JSON:API errors: http://jsonapi.org/format/#error-objects
if (err.errors) err.errors.forEach(error => { ... })
// Error type (Error, TypeError etc.)
err.name
// Error message
err.message
// Axios request parameters
err.config
// Axios response parameters
err.response
}
Handling errors (Promises)
api.get('anime')
.then(({ data }) => { ... })
.catch(err => {
// Array of JSON:API errors: http://jsonapi.org/format/#error-objects
if (err.errors) err.errors.forEach(error => { ... })
// Error type (Error, TypeError etc.)
err.name
// Error message
err.message
// Axios request parameters
err.config
// Axios response parameters
err.response
})
Returns Object JSON-parsed response
packages/kitsu/src/index.js:250-271
Update a resource (alias update)
model string Resource to update data in. Expected formats are :resource, :resource/:id, :resource/:id/:relationship or :resource/:id/relationships/:relationshipbody (Object | Array<Object>) Data to send in the requestheaders Object? Additional headers to send with the request (optional, default {})Update a resource
api.update('posts', {
id: '1',
content: 'Goodbye World'
})
Update a resource with relationships
api.update('posts', {
content: 'Hello World',
uploads: {
id: '167585',
type: 'uploads'
}
})
Clear to-one relationships from a resource
api.update('posts/1/relationships/uploads', null)
Clear to-many relationships from a resource
api.update('posts/1/relationships/uploads', [])
Update multiple resources (API must support the Bulk Extension)
api.update('posts', [
{ id: '1', content: 'Hello World' },
{ id: '2', content: 'Another post' }
])
Returns (Object | Array<Object>) JSON-parsed response
packages/kitsu/src/index.js:299-318
Create a new resource (alias create)
model string Resource to create. Expected formats are :resource, :resource/:id, :resource/:id/:relationship or :resource/:id/relationships/:relationshipbody (Object | Array<Object>) Data to send in the requestheaders Object? Additional headers to send with the request (optional, default {})Create a post on a user's profile feed
api.create('posts', {
content: 'Hello World',
targetUser: {
id: '42603',
type: 'users'
},
user: {
id: '42603',
type: 'users'
}
})
Create multiple resources (API must support the Bulk Extension)
api.create('posts', [
{ content: 'Hello World' },
{ content: 'Another post' }
])
Returns (Object | Array<Object>) JSON-parsed response
packages/kitsu/src/index.js:333-362
Remove a resource (alias remove)
model string Resource to remove. Expected formats are :resource, :resource/:id/:relationship or :resource/:id/relationships/:relationshipid (string | number | Array<number>) Resource ID to remove. Pass an array of IDs to delete multiple resources (Bulk Extension)headers Object? Additional headers to send with the request (optional, default {})Remove a single resource
api.delete('posts', 123)
Remove multiple resources (API must support the Bulk Extension)
api.delete('posts', [ 1, 2 ])
Returns (Object | Array<Object>) JSON-parsed response
packages/kitsu/src/index.js:384-391
Get the authenticated user's data
Note Requires the JSON:API server to support filter[self]=true
params Object? JSON-API request queries (optional, default {})
params.fields Object? Return a sparse fieldset with only the included attributes/relationships - JSON:API Sparse Fieldsetsparams.include string? Include relationship data - JSON:API Includesheaders Object? Additional headers to send with the request (optional, default {})Get the authenticated user's resource
api.self()
Using JSON:API parameters
api.self({
fields: {
users: 'name,birthday'
}
})
Returns Object JSON-parsed response
packages/kitsu/src/index.js:452-472
Send arbitrary requests
Note Planned changes to the get, patch, post and delete methods in a future major release may make this method redundent. See https://github.com/wopian/kitsu/issues/415 for details.
config Object? Request configuration
config.body (Object | Array<Object>)? Data to send in the requestconfig.method string? Request method - GET, PATCH, POST or DELETE (defaults to GET, case-insensitive)config.params Object? JSON-API request queries. Any JSON:API query parameter not mentioned below is supported out of the box.
config.params.page Object? JSON:API Pagination. All pagination strategies are supported, even if they are not listed below.
config.params.page.limit number? Number of resources to return in request (Offset-based) - Note: For Kitsu.io, max is 20 except on libraryEntries which has a max of 500config.params.page.offset number? Number of resources to offset the dataset by (Offset-based)config.params.page.number number? Page of resources to return in request (Page-based) - Note: Not supported on Kitsu.ioconfig.params.page.size number? Number of resources to return in request (Page-based and cursor-based) - Note: Not supported on Kitsu.ioconfig.params.page.before string? Get the previous page of resources (Cursor-based) - Note: Not Supported on Kitsu.ioconfig.params.page.after string? Get the next page of resources (Cursor-based) - Note: Not Supported on Kitsu.ioconfig.type string The resource typeconfig.url string The URL path of the resourceheaders Object? Additional headers to send with the request (optional, default {})Raw GET request
api.request({
url: 'anime/1/mappings',
type: 'mappings',
params: { filter: { externalSite: 'aozora' } }
})
Raw PATCH request
api.request({
method: 'PATCH',
url: 'anime',
type: 'anime',
body: { id: '1', subtype: 'tv' }
})
Raw POST request
api.request({
method: 'PATCH',
url: 'anime',
type: 'anime',
body: { subtype: 'tv' }
})
Raw DELETE request
api.request({
method: 'DELETE',
url: 'anime/1',
type: 'anime',
body: { id: '1' }
})
Bulk Extension support (PATCH, POST & DELETE)
api.request({
method: 'PATCH',
url: 'anime',
type: 'anime',
body: [
{ id: '1', subtype: 'tv' }
{ id: '2', subtype: 'ona' }
]
})
Returns Object JSON-parsed response
See CONTRIBUTING
See CHANGELOG
All code released under MIT
FAQs
A simple, lightweight & framework agnostic JSON:API client using Axios
The npm package kitsu receives a total of 4,810 weekly downloads. As such, kitsu popularity was classified as popular.
We found that kitsu demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer 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.
Research
Security News
Socket’s threat research team has detected six malicious npm packages typosquatting popular libraries to insert SSH backdoors.
Security News
MITRE's 2024 CWE Top 25 highlights critical software vulnerabilities like XSS, SQL Injection, and CSRF, reflecting shifts due to a refined ranking methodology.
Security News
In this segment of the Risky Business podcast, Feross Aboukhadijeh and Patrick Gray discuss the challenges of tracking malware discovered in open source softare.