noelanimanini / api-docs

🤖 API documentation for Kitsu

API Docs

Kitsu is a modern anime discovery platform that helps you track the anime you're watching, discover new anime and socialize with other fans.

---

This is our api docs repository.
Check out the tools, web, mobile and server repositories.

---

Documentation

Legacy documentation is available on Apiary: https://kitsu.docs.apiary.io/

The API documentation is currently being converted from API Blueprint to OpenAPI 3. You can view the progress at: https://hummingbird-me.github.io/api-docs and hummingbird-me#71

Contributing

The documentation is written with OpenAPI 3 and YAML 1.2. Trivial changes can be added using GitHub's built-in editor. For bigger changes it is advised to follow the steps below.

If you have any questions you can:

• Ask us in #api on our Discord server
• Ping @wopian, @matthewdias or @nuck on Kitsu.

File Structure

The OpenAPI schema is split into multiple directories. While it looks complicated, it reduces the amount of repeated parameters and resource attributes/relationships to near zero.

Resource, relationship and filter inheritence matches the model definitions on the server repo.

api
├───parameters  # Query Parameters
│   └───path    # Path Parameters
│
├───paths       # Endpoints, grouped by tagGroups
│
├───resources   # Top-level JSON:API resource structures (one, many, included)
│   ├───anime
│   └───error   # JSON:API error responses
│
└───schemas                       # Data Models
    ├───enums
    │
    ├───filters                   # Reusable JSON:API filter parameters
    │   ├───resource              # Root filter parameter for each resource
    │   └───resourceFilters       # Grouped filters (inheritance)
    │
    ├───links                     # JSON:API link properties
    │
    ├───meta                      # JSON:API meta properties
    │
    └───resources                 # JSON:API resources
        ├───relationships         # JSON:API relationships
        └───resourceRelationships # Grouped relationships (inheritance)

Base Files

These are defined as seperate resources in the server definitions and are inherited by all other definitions. Check anime and media in api/schemas/resources and api/schemas/filters/resourceFilters to see how inheritance is applied.

Resources

All resources inherit from api/schemas/resources/base.yml

In addition:

• Sluggable resources inherit from api/schemas/resources/base_sluggable.yml
• Episodic resources inherit from api/schemas/resources/base_episodic.yml

Resource Relationships

• Episodic resources inherit from api/schemas/resources/resourceRelationships/base_episodic.yml

Filters

All resources inherit from api/schemas/filters/resourceFilters/base.yml

In addiion:

• Sluggable resources inherit from api/schemas/filters/resourceFilters/base_sluggable.yml
• Episodic resources inherit from api/schemas/filters/resourceFilters/base_episodic.yml

Requirements

• git > 2.0.0
• node.js > 12.0.0
• yarn > 1.22.0

Development

1. Fork the repo

2. Clone the repo (git clone https://github.com/{yourusername}/api-docs.git)

3. Create a new branch (git checkout -b improve-docs)

4. Install dependencies (yarn)

5. Make the appropriate changes in the source files

• Check the changes locally with yarn start

6. Commit your changes (git commit -am 'feat: improve docs')

7. Push to your branch (git push origin improve-docs)

8. Create a Pull Request

Contributors