The backend of The Cheshire Cat plugin directory

$ docker compose up

Install requirements:

$ pip install -r requirements.txt

Start uvicorn server:

$ python ./main.py

Welcome to the API documentation for our plugin directory. Below, you'll find a list of available endpoints to interact with the system.

• List all Plugins (Paginated)
• List Excluded Plugins (Paginated)
• List Plugins by Author (Paginated)
• Get All Available Tags
• Get Plugins by Tag (Paginated)
• Download a Single Plugin (.zip)
• Search for a Plugin
• Get Plugins Analytics

GET /plugins

List all the plugins.

Order Parameter:

• order: Sort plugins list
  • oldest: Sort from oldest to newest (default)
  • newest: Sort from newest to older
  • popular: Sort from most popular
  • a2z: Sort alphabetically
  • z2a: Sort reverse alphabetically

Pagination Parameters:

• page: Query the page number.
• page_size: Query the number of elements per page.

Example: Return the second page, 3 plugins per page ordered from newest to oldest

/plugins?page=2&page_size=3&order=newest

POST /excluded

List the plugins excluding the ones you pass in the body.

Request Body:

{
  "excluded": ["plugin to exclude", "other plugin I don't want"]
}

Pagination Parameters:

• page: Query the page number.
• page_size: Query the number of elements per page.

Example: Return the second page, 3 plugins per page

/exclude?page=2&page_size=3

POST /author

List all the plugins from a specific author.

Request Body:

{
  "author_name": "Nicola Corbellini"
}

Pagination Parameters:

• page: Query the page number.
• page_size: Query the number of elements per page.

Example: Return the second page, 3 plugins per page

/author?page=2&page_size=3

GET /tags

Return the list of all available plugins' tags.

GET /tag/{tag}

Return all the plugins that have a specific tag.

Pagination Parameters:

• page: Query the page number.
• page_size: Query the number of elements per page.

Example: Return the second page, 3 plugins per page

/tag/{tag}?page=2&page_size=3

POST /download

Download a single plugin in .zip format.

Request Body:

{
  "url": "https://github.com/pieroit/meow-todo-list"
}

POST /search

Search for a plugin. This will perform a search in plugins' description, name, author, and tags.

Request Body:

{
  "query": "llm embedding nicola corbellini"
}

GET /analytics

Return all the plugins' analytics.

GET /analytics/graph

Return an HTML webpage with an image of plugins' analytics graph.

GET /plugins_table

Get an html page containing all plugins.

Optional Parameters:

• columns: A comma separated list of fields that will be filtered. Possible values are: "name", "description" "author_name", "author_url", "plugin_url", "tags", "thumb", "version", "url", "downloads" - default is all fields shown inside table
• render_link: If True will transform URL into hyperlynks - default is False
• classes: Add css classes on <table> element - default is "plugins-table"

Example: Show only name plugin_url and author_name, use hyperlynks and add foo as css class:

/plugins_table?columns=name,plugin_url,author_name&render_link=True&classes=foo

The validation process for the plugin.json manifest ensures the integrity and usability of plugins within the repository. To successfully pass validation, the plugin.json file must reside within the main branch of the repository and include essential fields such as "name" and "author_name". While other fields remain optional, including additional information not only enhances the user experience but also improves searchability within the directory. Maintaining these validation criteria not only guarantees the quality of plugins but also contributes to a more robust and user-friendly plugin ecosystem.

Our caching system is designed to optimize performance and reduce redundant operations. Currently, most of the caching is memory-based, which means it gets reset upon system shutdown. Additionally, our cache is invalidated on a daily basis, precisely every 1440 minutes.

When the /download endpoint is initially called, our system sets up two essential folders: zip_cache and repository_cache.

• zip_cache stores the release zip files or acts as a creation location if there are no existing releases on GitHub.
• repository_cache is used to clone repositories that lack releases.

We employ a comprehensive strategy to determine whether a repository or release has been downloaded and whether it's up-to-date. If the repository is present and current, we retrieve and provide the existing zip file. However, if the repository is outdated or if any issues arise while verifying its status, the existing repository is deleted. Subsequently, we initiate a fresh download to ensure accuracy.

This approach serves two key purposes: efficient repository caching and the prevention of unnecessary cloning operations when a repository is already available and up-to-date.

The implementation of analytics within our plugin's directory is designed with utmost consideration for user privacy. We maintain an analytics.json file that is updated each time a plugin is downloaded, providing us with valuable insights into usage trends without compromising individual user identities. Importantly, we do not track unique downloads or store any sensitive data such as IP addresses. Our approach to analytics prioritizes user privacy, ensuring that our data collection methods, while not overly precise, remain fair and respectful of the privacy of our users. This commitment to data ethics underscores our dedication to creating a transparent and user-friendly environment within our plugin ecosystem.