arjunashok commented on code in PR #293: URL: https://github.com/apache/cassandra-sidecar/pull/293#discussion_r2632852496
########## CONTRIBUTING.md: ########## @@ -445,3 +479,110 @@ The `CassandraAdapterFactory` has a version tag which represents the minimum ver When adding shims, implement the minimum necessary changes in the new package and name all classes with a version number after the word `Cassandra`. For example, if `base`'s minimum version is moved to 5.0, a Cassandra40 adapter package/subproject should be added, with a minimum version of 4.0.0. Within that project, the classes should all be named `Cassandra40*`, so `Cassandra40Adapter`, `Cassandra40Factory`, etc. + +### <a name="api-design"></a> RESTful API Design Guidelines + +We should primarily follow RESTful design principles as they provide a clear, standardized, and scalable approach to resource management. For practical implementation guidance on adding new APIs to the codebase, please refer to the [Introducing New APIs](#new-apis) section. + +* The API design must conform to the RESTful design principles outlined below +* Design proposal must include the request and response structure with HTTP method, description and the complete URL. Each request field should be annotated as required or optional. +* API implementation must have sufficient input validation to catch injection of commands in fields and to fail-fast on invalid requests with a HTTP 400 BAD_REQUEST status code. See the [Requests and Responses](#requests-and-responses) section below. +* Design APIs with single responsibility principle. +* Do not expose internal implementation details either in the API URL or the response. Since the API is the external interface and contract with the clients, it should be generic enough to be loosely coupled to internal implementation. eg. When exposing Cassandra operations that are internally grouped under StorageService need not be reflected in the URI, unless it actually corresponds to the use-case or resource being operated upon. +* Do not make the API specific to a version of Cassandra. One of the design goals of the Sidecar is to abstract the complexity in managing multiple versions of Cassandra and as such strive to provide the same APIs irrespective of the version of Cassandra. +* The Sidecar APIs must maintain compatibility with the current trunk version of Apache Cassandra as well as all officially supported prior versions until their respective End-of-Life (EOL) dates. <supported Sidecar versions README> + * Support for versions that have reached EOL should be deprecated in Sidecar APIs with clear communication and a defined sunset period + * New features or breaking changes in the Sidecar API should be introduced in a backward-compatible manner or versioned accordingly. + * Testing and validation must cover the trunk and all supported versions to guarantee consistent behavior and reliability. + +#### Design Principles + +1. Resource Naming - Use nouns in endpoint URLs to represent resources, not verbs (See exceptions). The HTTP method (GET, POST, PUT, DELETE) should define the action. Review Comment: yep it's redundant with item 2. removed the sentence. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
