Clean and Standardize OpenAPI Documentation

[bencap]

These changes ballooned a lot from the initial scope, but should reflect a substantial improvement in the quality of our OpenAPI documentation, both in terms of usability and maintainability.

This pull request introduces significant improvements to the API routers and error handling across several modules, focusing on consistent response formatting, clearer documentation, and stricter access control. The changes enhance the maintainability and usability of the API by standardizing route metadata, error responses, and permission checks.

API Router and Metadata Standardization

• Updated routers across the codebase to use shared constants for prefixes and error responses, and added descriptive metadata and summaries for endpoints to improve documentation and consistency. [1] [2] [3]

Access Control and Error Handling

• Replaced custom status code usage with standardized error responses and stricter permission checks in authorization-related functions, ensuring forbidden actions consistently return HTTP 403 and missing resources return HTTP 404. [1] [2] [3] [4] [5]

Collection and Resource Management

• Enhanced endpoints for managing collections, score sets, and experiments by updating response codes (e.g., using 409 for association conflicts), clarifying endpoint summaries, and improving error messages for better client feedback. [1] [2] [3] [4]

Improved Logging and Security

• Strengthened logging around sensitive actions (e.g., deleting access keys) and ensured endpoints never reveal the existence of resources not owned by the user, improving security and auditability.

Miscellaneous Corrections

• Fixed status codes for taxonomy search and collection creation errors to better reflect client and server errors (e.g., using 400 for bad requests and 500 for server-side issues). [1] [2] [3]