wopianKitsu
A simple, lightweight & framework agnostic JSON:API client using Axios
Migration guide for v10 & previous major releases
#
Features
- JSON-API 1.0 compliant
- Automatically links relationships to data
- Works in Node & browsers
- Uses the Promise API
Node / Browser Support
| Package | Package Size* |
ESM Size† | Node | Chrome | Firefox | Safari | Edge |
|---|---|---|---|---|---|---|---|
kitsu |
≤ 8.7 kb | ≤ 8.6 KB | 14+ | 83+ | 78+ | 13.1+ | 95+ |
* Including all dependencies & minified with brotli † EcmaScript Modules package size*
Response Comparison
json5
{
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'
}
}
]
}
json5
{
data: {
id: '1'
type: 'articles'
title: 'JSON API paints my bikeshed'
author: {
data: {
id: '42'
type: 'people'
name: 'John'
}
}
}
}
Install
Yarn / NPM
yarn add kitsu
npm install kitsuimport Kitsu from "kitsu"; // ES Modules & Babel
const Kitsu = require("kitsu"); // CommonJS & BrowserifyQuick Start
// kitsu.app'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', { params: { 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', {
params: {
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.app's API, their API docs lists all available resources with their attributes & relationships
Contributing
See CONTRIBUTING
Releases
See CHANGELOG
License
All code released under MIT
API
Table of Contents
Kitsu
packages/kitsu/src/index.js:31-567
Creates a new kitsu instance
Parameters
optionsObject? Options (optional, default{})options.baseURLstring Set the API endpoint (optional, default'https://kitsu.app/api/edge')options.headersObject? Additional headers to send with the requestsoptions.query("traditional"|"modern"| Function) Query serializer function to use. This will impact the way keys are serialized when passing arrays as query parameters. 'modern' is recommended for new projects. (optional, defaulttraditional)options.camelCaseTypesboolean If enabled,typewill be converted to camelCase from kebab-casae or snake_case (optional, defaulttrue)options.resourceCase("kebab"|"snake"|"none") Case to convert camelCase to.kebab-/library-entries;snake- /library_entries;none-/libraryEntries` (optional, defaultkebab)options.pluralizeboolean If enabled,/userwill become/usersin the URL request andtypewill be pluralized in POST, PATCH and DELETE requests (optional, defaulttrue)options.timeoutnumber Set the request timeout in milliseconds (optional, default30000)options.axiosOptionsObject? Additional options for the axios instance (see axios/axios#request-config for details)
Examples
Using with kitsu.app'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'
}
})plural
packages/kitsu/src/index.js:58-59
- See: https://www.npmjs.com/package/pluralize for documentation
- See: Kitsu constructor options for disabling pluralization
If pluralization is enabled (default, see Kitsu constructor docs) then pluralization rules can be added
Examples
Adding an uncountable pluralization rule
api.plural.plural('paper') //=> 'papers'
api.plural.addUncountableRule('paper')
api.plural.plural('paper') //=> 'paper'headers
packages/kitsu/src/index.js:73-73
Get the current headers or add additional headers
Examples
Get all headers
api.headersGet 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
interceptors
packages/kitsu/src/index.js:120-120
- See: https://github.com/axios/axios#interceptors for documentation
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.
Examples
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)get
packages/kitsu/src/index.js:218-253
Fetch resources (alias fetch)
Parameters
modelstring Resource to fetch data from. Expected formats are:resource,:resource/:id,:resource/:id/:relationshipor:resource/:id/relationships/:relationshipconfigObject? Additional configuration (optional, default{})config.headersObject? Additional headers to send with the requestconfig.paramsObject? JSON:API request queries. JSON:API query parameters not listed are supportedconfig.params.fieldsObject? Return a sparse fieldset with only the included attributes/relationships - JSON:API Sparse Fieldsetsconfig.params.filterObject? Filter dataset by attribute values - JSON:API Filteringconfig.params.includestring? Include relationship data - JSON:API Includesconfig.params.sortstring? Sort dataset by one or more comma separated attributes (prepend-for descending order) - JSON:API Sortingconfig.params.pageObject? JSON:API Pagination. All pagination strategies are supported, even if they are not listed below.config.params.page.limitnumber? Number of resources to return in request (Offset-based) - Note: For kitsu.app, max is20except onlibraryEntrieswhich has a max of500config.params.page.offsetnumber? Number of resources to offset the dataset by (Offset-based)config.params.page.numbernumber? Page of resources to return in request (Page-based) - Note: Not supported on kitsu.appconfig.params.page.sizenumber? Number of resources to return in request (Page-based and cursor-based) - Note: Not supported on kitsu.appconfig.params.page.beforestring? Get the previous page of resources (Cursor-based) - Note: Not Supported on kitsu.appconfig.params.page.afterstring? Get the next page of resources (Cursor-based) - Note: Not Supported on kitsu.app
config.axiosOptionsObject? Additional options for the axios instance (see axios/axios#request-config for details)
Examples
Getting a resource with JSON:API parameters
api.get('users', {
params: {
fields: {
users: 'name,birthday'
},
filter: {
name: 'wopian'
}
}
})Getting a collection of resources with their relationships
api.get('anime', {
params: {
include: 'categories'
}
})Getting a single resource by ID (method one)
api.get('anime/2', {
params: {
include: 'categories'
}
})Getting a single resource by ID (method two)
api.get('anime', {
params: {
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.app's API)
// resource?filter[x][y]=value
api.get('resource', {
params: {
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 Promise[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object) JSON-parsed response
patch
packages/kitsu/src/index.js:289-323
Update a resource (alias update)
Parameters
modelstring Resource to update data in. Expected formats are:resource,:resource/:id,:resource/:id/:relationshipor:resource/:id/relationships/:relationshipbody(Object | Array[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)) Data to send in the requestconfigObject? Additional configuration (optional, default{})config.paramsObject? JSON:API request queries. See #get for documentationconfig.headersObject? Additional headers to send with the requestconfig.axiosOptionsObject? Additional options for the axios instance (see axios/axios#request-config for details)
Examples
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 Promise<(Object | Array[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object))> JSON-parsed response
post
packages/kitsu/src/index.js:358-390
Create a new resource (alias create)
Parameters
modelstring Resource to create. Expected formats are:resource,:resource/:id,:resource/:id/:relationshipor:resource/:id/relationships/:relationshipbody(Object | Array[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)) Data to send in the requestconfigObject? Additional configuration (optional, default{})config.paramsObject? JSON:API request queries. See #get for documentationconfig.headersObject? Additional headers to send with the requestconfig.axiosOptionsObject? Additional options for the axios instance (see axios/axios#request-config for details)
Examples
Create a post on a user's profile feed
api.create('posts', {
content: 'Hello World',
targetUser: {
data: {
id: '42603',
type: 'users'
}
},
user: {
data: {
id: '42603',
type: 'users'
}
}
})Create multiple resources (API must support the Bulk Extension)
api.create('posts', [
{ content: 'Hello World' },
{ content: 'Another post' }
])Returns Promise<(Object | Array[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object))> JSON-parsed response
delete
packages/kitsu/src/index.js:410-450
Remove a resource (alias remove)
Parameters
modelstring Resource to remove. Expected formats are:resource,:resource/:id/:relationshipor:resource/:id/relationships/:relationshipid(string | number | Array[number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)) Resource ID to remove. Pass an array of IDs to delete multiple resources (Bulk Extension)configObject? Additional configuration (optional, default{})config.paramsObject? JSON:API request queries. See #get for documentationconfig.headersObject? Additional headers to send with the requestconfig.axiosOptionsObject? Additional options for the axios instance (see axios/axios#request-config for details)
Examples
Remove one or more relationships from a resource
api.delete('posts/1/relationships/uploads', [456, 789])Remove a single resource
api.delete('posts', 123)Remove multiple resources (API must support the Bulk Extension)
api.delete('posts', [ 1, 2 ])Returns Promise<(Object | Array[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object))> JSON-parsed response
self
packages/kitsu/src/index.js:474-483
Get the authenticated user's data
Note Requires the JSON:API server to support filter[self]=true
Parameters
configObject? Additional configuration (optional, default{})config.paramsObject? JSON:API request queries. See #get for documentationconfig.headersObject? Additional headers to send with the requestconfig.axiosOptionsObject? Additional options for the axios instance (see axios/axios#request-config for details)
Examples
Get the authenticated user's resource
api.self()Using JSON:API parameters
api.self({
params: {
fields: {
users: 'name,birthday'
}
}
})Returns Promise[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object) JSON-parsed response
request
packages/kitsu/src/index.js:538-566
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.
Parameters
configObject Request configurationconfig.body(Object | Array[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object))? Data to send in the requestconfig.methodstring? Request method -GET,PATCH,POSTorDELETE(defaults toGET, case-insensitive)config.paramsObject? JSON:API request queries. See #get for documentationconfig.typestring The resource typeconfig.urlstring The URL path of the resourceconfig.headersObject? Additional headers to send with the requestconfig.axiosOptionsObject? Additional options for the axios instance (see axios/axios#request-config for details)
Examples
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 Promise[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object) JSON-parsed response