A simple, lightweight & framework agnostic JSON:API client using Axios
Migration guide for v10 & previous major releases
| Package | Package Size* | ESM Size† | Node | Chrome | Firefox | Safari | Edge |
|---|---|---|---|---|---|---|---|
kitsu | ≤ 8.6 kb | ≤ 8.4 KB | 10+ | 69+ | 68+ | 12+ | 18+ |
* Including all dependencies & minified with brotli † EcmaScript Modules package size*
{
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
See [CONTRIBUTING]
See [CHANGELOG]
All code released under [MIT]
// 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
}
})
[More Examples]
If you're working with [Kitsu.io]'s API, their [API docs][kitsu.io api docs] lists all available resources with their attributes & relationships
packages/kitsu/src/index.js:31-482
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:53-54
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:68-68
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:113-113
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:191-211
Fetch resources (alias fetch)
model string Resource to fetch data from. Expected formats are :resource, :resource/:id, :resource/:id/:relationship or :resource/:id/relationships/:relationshipconfig Object? Additional configuration (optional, default {})
config.headers Object? Additional headers to send with the requestconfig.params Object? JSON:API request queries. JSON:API query parameters not listed are supported
config.params.fields Object? Return a sparse fieldset with only the included attributes/relationships - JSON:API Sparse Fieldsetsconfig.params.filter Object? Filter dataset by attribute values - JSON:API Filteringconfig.params.include string? Include relationship data - JSON:API Includesconfig.params.sort string? Sort dataset by one or more comma separated attributes (prepend - for descending order) - JSON:API Sortingconfig.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.ioGetting 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')
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:246-273
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 requestconfig Object? Additional configuration (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:303-328
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 requestconfig Object? Additional configuration (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:345-378
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)config Object? Additional configuration (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:399-408
Get the authenticated user's data
Note Requires the JSON:API server to support filter[self]=true
config Object? Additional configuration (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:462-481
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. See #get for documentationconfig.type string The resource typeconfig.url string The URL path of the resourceconfig.headers Object? Additional headers to send with the requestRaw 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
10.0.0-alpha.5 (2020-08-04)
FAQs
A simple, lightweight & framework agnostic JSON:API client using Axios
The npm package kitsu receives a total of 3,542 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.
Security News
A Stanford study reveals 9.5% of engineers contribute almost nothing, costing tech $90B annually, with remote work fueling the rise of "ghost engineers."
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.