/kitsu

🦊 A Simple framework agnostic JSON:API client

Primary LanguageJavaScriptMIT LicenseMIT

Kitsu

npm badge npm install badge david badge contributors badge donate badge

travis badge appveyor badge david dev badge cc maintainability badge cc coverage badge

A Simple framework agnostic JSON:API client for Kitsu.io and other spec compliant APIs

For breaking changes in 3.0, check the CHANGELOG

Features

  • Fully JSON-API compliant
  • Automatically links relationships to data
  • Works in Node and on the web
  • Uses the Promise API
  • Configurable timeout handling

Install

Yarn

yarn add kitsu

NPM 5

npm install kitsu

Response Comparison

A GET request to a JSON:API API returns:

{
  data: [
    {
      id: '4923ee67-19b0-4093-8aee-ab6ceeecf784'
      type: 'users'
      attributes: {
        name: 'wopian'
      }
      relationships: {
        followers: {
          data: [
            {
              id: '50cfe2db-8157-4999-be87-450fea1b4b52'
              type: 'follows'
            }
          ]
        }
      }
    }
  ]
  included: [
    {
      id: '50cfe2db-8157-4999-be87-450fea1b4b52'
      type: 'follows'
      attributes: {
        createdAt: '2017-08-24T02:36:26.006Z'
      }
    }
  ]
}

A GET request made with kitsu returns:

{
  data: [
    {
      id: '4923ee67-19b0-4093-8aee-ab6ceeecf784'
      type: 'users'
      name: 'wopian'
      followers: [
        {
          id: '50cfe2db-8157-4999-be87-450fea1b4b52'
          type: 'follows'
          createdAt: '2017-08-24T02:36:26.006Z'
        }
      ]
    }
  ]
}

Usage

// ES2015+/Babel
import Kitsu from 'kitsu'
// CommonJS/Browserify
const Kitsu = require('kitsu')

// For kitsu.io developers
const api = new Kitsu()

// For other JSON-API uses
// e.g api.example.org/2
const api = new Kitsu({
  baseURL: 'https://api.example.org',
  version: 2
})

// Get a collection of resources
api.get('anime').then(res => console.log(res))

// Get a resource
api.get('anime/1')

// Get a resource's relationship
api.get('anime/1/episodes')

// Create a resource
api.create('post', {
  content: 'some content'
})

// Update a resource
api.update('post', {
  id: '1',
  content: 'new content'
})

// Delete a resource
api.remove('post', 1)

// Destructuring with Async/Await
const { id } = await kitsu.get('users', {
  filter: { id: 2 }
})

More Examples

Docs

You can find the kitsu package documentation here

If you're working with Kitsu.io's API, their API documentation lists all available models with their attributes and relationships

Contributing

See CONTRIBUTING

Releases

See CHANGELOG

License

All code released under MIT