A simple, lightweight & framework agnostic JSON:API client for Kitsu.io and other APIs
Migration guide for v9 and previous major releases
| Package | Package Size* | Node | Chrome | Firefox | Safari | Edge |
|---|---|---|---|---|---|---|
kitsu | ≤ 8.6 kb | 10+ | 79+ | 68+ | 12.1+ | 18+ |
* Including all dependencies, minified & gzipped
{
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 and Babel
const Kitsu = require('kitsu') // CommonJS and 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 and relationships
packages/kitsu/src/index.js:30-342
Creates a new kitsu instance
options Object Options (optional, default {})
options.baseURL string Set the API endpoint (default https://kitsu.io/api/edge)options.headers Object Additional headers to send with requestsoptions.camelCaseTypes boolean If true, the type value will be camelCased, e.g library-entries and library_entries become libraryEntries (default true)options.resourceCase string kebab, snake or none. If kebab, /libraryEntries will become /library-entries. If snake, /libraryEntries will become /library_entries, If none, /libraryEntries will be unchanged (default kebab)options.pluralize boolean If true, /user will become /users in the URL request and type will be pluralized in post, patch and delete requests - user -> users (default true)options.timeout number Set the request timeout in milliseconds (default 30000)options.axiosOptions Object Additional options for the axios instanceUsing 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:111-111
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 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:184-203
Fetch resources (alias fetch)
model string Model to fetch data fromparams Object JSON-API request queries (optional, default {})
params.page Object JSON:API Pagination
params.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 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')
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:219-239
Update a resource (alias update)
model string Model to update data inbody Object Data to send in the requestheaders Object Additional headers to send with request (optional, default {})Update a post
api.update('posts', {
id: '12345678',
content: 'Goodbye World'
})
Returns Object JSON-parsed response
packages/kitsu/src/index.js:262-281
Create a new resource (alias create)
model string Model to create a resource underbody Object Data to send in the requestheaders Object Additional headers to send with 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'
}
})
Returns Object JSON-parsed response
packages/kitsu/src/index.js:294-312
Remove a resource (alias remove)
model string Model to remove data fromid (string | number) Resource ID to removeheaders Object Additional headers to send with request (optional, default {})Remove a user's post
api.delete('posts', 123)
Returns Object JSON-parsed response
packages/kitsu/src/index.js:334-341
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 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
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 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
Research
Socket researchers have discovered malicious npm packages targeting crypto developers, stealing credentials and wallet data using spyware delivered through typosquats of popular cryptographic libraries.
Security News
Socket's package search now displays weekly downloads for npm packages, helping developers quickly assess popularity and make more informed decisions.
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."