Skip to content

hummingbird-me/api-docs

Repository files navigation

API Docs

API Docs Deployment

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 #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:

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

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
  1. Commit your changes (git commit -am 'feat: improve docs')

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

  3. Create a Pull Request

Contributors