mirror of
https://github.com/advplyr/audiobookshelf.git
synced 2026-05-30 23:40:40 +02:00
[PR #3388] Initial proposed new routes #3956
Assignees
adam (Adam Melkus)
Clear assignees
adam (Adam Melkus)
No Assignees
Notifications
Due Date
No due date set.
Dependencies
No dependencies set.
Reference: starred/audiobookshelf#3956
Reference in New Issue
Block a user
Delete Branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
📋 Pull Request Information
Original PR: https://github.com/advplyr/audiobookshelf/pull/3388
Author: @nichwall
Created: 9/8/2024
Status: 🔄 Open
Base:
master← Head:proposed_routes📝 Commits (10+)
b42fcf2Initial proposed new/libraries/{id}/itemsroutes9cc3caaInitial: new root spec for all endpointsc7db327Add: initial podcast endpointsd89c977Add: initial library media endpoints2883863Add: podcast-episodes, claen up parameters0795b03Add: author endpointscb2a8b3Add: create and delete library1f10f47Additional library endpoints1556a04Add: ereader endpointsda6afc7Add: RSS Feed endpoints📊 Changes
2 files changed (+6718 additions, -0 deletions)
View changed files
📝
docs/controllers/LibraryController.yaml(+399 -0)➕
docs/newRoot.yaml(+6319 -0)📄 Description
This PR is an attempt at proposing some new API endpoints to better facilitate an OpenAPI spec and allow for easier changes to the API to match more closely with the new data model.
From the perspective of the OpenAPI spec, we want each endpoint to have only one return type. While the OpenAPI specification is able to include different return schemas for a single endpoint, support for this varies by tool and language generator. Many (all?) tools do not fully implement all aspects of OpenAPI 3.0. In order to achieve this goal, I propose that new endpoints are defined for each media media type (book, podcast, and podcast episode).
For example, if we can split the
/libraries/{id}/itemsendpoint into 3 different endpoints with distinct return types, this will make the OpenAPI spec much simpler and reduce the information loaded and sent to the client. If a client needs more information about a specific book, podcast, or episode, the relevant endpoints would be queried./libraries/{id}/books/libraries/{id}/podcasts/libraries/{id}/podcast-episodesHere is a list of what I think the new routes could be. Note that all of these are new endpoints so they can be developed as their own controller without breaking existing endpoints, and then switching the web client over to using the new endpoints to ensure everything is working correctly before deprecating any other endpoints. Some of these endpoints will be a little clunky with the current database, but once migrations are set up https://github.com/advplyr/audiobookshelf/pull/3378 then we can migrate some things around (like simplifying the file endpoints).
/book/{id}GETPATCHlibraryItemand themediaobjects.DELETE/book/{id}/downloadGET/book/{id}/coverGETPOSTPATCHDELETE/book/{id}/matchPOST/book/{id}/playPOST/book/{id}/tracksPATCH/book/{id}/scanPOST/book/{id}/metadata-objectGET/book/{id}/chaptersPOST/book/{id}/ebookGETfileIdinstead of having it as part of the path, otherwise default to primary ebook if it exists.PATCHfileIdand requestBody includes whether it should be primary or not./podcast/{id}GETPATCHlibraryItemand themediaobjects.DELETE/podcast/{id}/downloadGET/podcast/{id}/coverGETPOSTPATCHDELETE/podcast/{id}/matchPOST/podcast/{id}/playPOST/podcast/{id}/scanPOST/podcast/{id}/metadata-objectGET/podcast-episode/{id}GETPATCHDELETE/podcast-episode/{id}/downloadGET/file/{id}/downloadendpoint./podcast-episode/{id}/matchPOST/podcast-episode/{id}/playPOST/file/{id}GET/file/{id}/ffprobeGET/file/{id}/downloadGET🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.