The backend of The Cheshire Cat plugin directory
$ docker compose upInstall requirements:
$ pip install -r requirements.txtStart uvicorn server:
$ python ./main.pyWelcome 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 listoldest: Sort from oldest to newest (default)newest: Sort from newest to olderpopular: Sort from most populara2z: Sort alphabeticallyz2a: 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 tablerender_link: IfTruewill transform URL into hyperlynks - default isFalseclasses: 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_cachestores the release zip files or acts as a creation location if there are no existing releases on GitHub.repository_cacheis 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.