A simple, lightweight & framework agnostic JSON:API client for Kitsu.io and other APIs
Check out the Migration Guide for breaking changes and new features in 5.x
| Package | Package Size* | Node | Chrome | Firefox | Safari | Edge | IE |
|---|---|---|---|---|---|---|---|
kitsu | 17.8 kb | 6+ | 51+ | 47+ | 9.1+ | 14+ | |
kitsu/legacy | 19.7 kb | 6+ | 4+ | 3+ | 3.1+ | 12+ | 8+ |
kitsu/node | 14.6 kb | 6+ |
* 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: {
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
const Kitsu = require('kitsu/legacy') // Legacy IE8+ support
const Kitsu = require('kitsu/node') // Lighter node-only package
<script src='https://bundle.run/kitsu@5?name=Kitsu'></script>
<script src='https://bundle.run/kitsu@5/legacy/index.js?name=Kitsu'></script>
// 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/1')
api.fetch('anime/1/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
api.remove('post', 1)
If you're working with Kitsu.io's API, their API docs lists all available resources with their attributes and relationships
Creates a new kitsu instance
Parameters
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)Examples
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'
}
})
Fetch resources (alias fetch)
Parameters
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 {})Examples
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
Get the current headers or add additional headers
Examples
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
Update a resource (alias update)
Parameters
model string Model to update data inbody Object Data to send in the requestheaders Object Additional headers to send with request (optional, default {})Examples
Update a post
api.update('posts', {
id: '12345678',
content: 'Goodbye World'
})
Returns Object JSON-parsed response
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'
Create a new resource (alias create)
Parameters
model string Model to create a resource underbody Object Data to send in the requestheaders Object Additional headers to send with request (optional, default {})Examples
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
Remove a resource
Parameters
model string Model to remove data fromid (string | number) Resource ID to removeheaders Object Additional headers to send with request (optional, default {})Examples
Remove a user's post
api.remove('posts', 123)
Returns Object JSON-parsed response
Get the authenticated user's data
Note Requires the JSON:API server to support filter[self]=true
Parameters
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 {})Examples
Get the authenticated user's resource
api.self()
Using JSON:API parameters
api.self({
fields: '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
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
PyPI confirms no security flaws were exploited in the Ultralytics supply chain attack and highlights improvements for safer package publishing.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.