You are viewing a plain text version of this content. The canonical link for it is here.
Posted to pr@cassandra.apache.org by "arjunashok (via GitHub)" <gi...@apache.org> on 2025/12/01 20:40:08 UTC

[PR] CASSSIDECAR-358 Adds API contribution and design guidelines [cassandra-sidecar]

arjunashok opened a new pull request, #293:
URL: https://github.com/apache/cassandra-sidecar/pull/293

   (no comment)


-- 
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: pr-unsubscribe@cassandra.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: pr-unsubscribe@cassandra.apache.org
For additional commands, e-mail: pr-help@cassandra.apache.org


Re: [PR] CASSSIDECAR-358 Adds API contribution and design guidelines [cassandra-sidecar]

Posted by "yifan-c (via GitHub)" <gi...@apache.org>.
yifan-c commented on code in PR #293:
URL: https://github.com/apache/cassandra-sidecar/pull/293#discussion_r2628237434


##########
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.
+2. Use HTTP Methods to denote the action to be performed on the resource and HTTP Response codes to denote the outcome of the operation. For more details, refer to  Requests and Responses
+3. URI Naming Conventions
+   * Follow a consistent usage of plural nouns for resources. eg. /keyspaces/123
+   * Should be all lower case, with "-" as the word separator.
+   * Use Sub-resources for Hierarchical Relationships. eg. Orders by a user can be scoped as nested resource within users resource -   /users/{userId}/orders/{orderId}.

Review Comment:
   add code marks for `/users/{userId}/orders/{orderId}`



##########
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.
+2. Use HTTP Methods to denote the action to be performed on the resource and HTTP Response codes to denote the outcome of the operation. For more details, refer to  Requests and Responses
+3. URI Naming Conventions
+   * Follow a consistent usage of plural nouns for resources. eg. /keyspaces/123
+   * Should be all lower case, with "-" as the word separator.
+   * Use Sub-resources for Hierarchical Relationships. eg. Orders by a user can be scoped as nested resource within users resource -   /users/{userId}/orders/{orderId}.
+4. Response Format
+   * Prefer to represent primitive types as corresponding types in JSON. eg.
+
+```json
+{
+"userId": 123,             // number
+"isActive": true,          // boolean
+"userName": "JohnDoe",     // string
+"createdDate": "2024-08-20T12:34:56Z" // string (for date-time)
+}
+```
+
+5. Pagination – do not return unbounded responses. Always ensure that the API responses are bounded to a reasonable default. eg. /users?page=2&limit=10
+6. Filtering & Sorting – Support filtering and sorting where applicable.
+7. Versioning - APIs must use semantic versioning, with the major-version encoded into the URL. For more information, see Lifecycle.
+
+#### Exceptions
+
+There may be cases where adhering strictly to REST may not be practical, such as cases where the application behavior does not fit into the state-machine model, dealing with complex workflows, real-time communication, or client-specific requirements. In these situations, minor deviations from REST principles may be necessary to meet specific needs, ensuring that the API remains effective and user-friendly.
+
+For example:
+When Casasndra node operations are mapped to APIs, like decommission or repair, the tradeoff has been made in favor of readability and single-responsibility when compared to a purely RESTful design.
+
+Current design:
+PUT /api/v1/cassandra/operations/decommission
+PUT /api/v1/cassandra/operations/repair

Review Comment:
   format the code



##########
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.
+2. Use HTTP Methods to denote the action to be performed on the resource and HTTP Response codes to denote the outcome of the operation. For more details, refer to  Requests and Responses
+3. URI Naming Conventions
+   * Follow a consistent usage of plural nouns for resources. eg. /keyspaces/123
+   * Should be all lower case, with "-" as the word separator.
+   * Use Sub-resources for Hierarchical Relationships. eg. Orders by a user can be scoped as nested resource within users resource -   /users/{userId}/orders/{orderId}.
+4. Response Format
+   * Prefer to represent primitive types as corresponding types in JSON. eg.
+
+```json
+{
+"userId": 123,             // number
+"isActive": true,          // boolean
+"userName": "JohnDoe",     // string
+"createdDate": "2024-08-20T12:34:56Z" // string (for date-time)
+}
+```
+
+5. Pagination – do not return unbounded responses. Always ensure that the API responses are bounded to a reasonable default. eg. /users?page=2&limit=10
+6. Filtering & Sorting – Support filtering and sorting where applicable.
+7. Versioning - APIs must use semantic versioning, with the major-version encoded into the URL. For more information, see Lifecycle.
+
+#### Exceptions
+
+There may be cases where adhering strictly to REST may not be practical, such as cases where the application behavior does not fit into the state-machine model, dealing with complex workflows, real-time communication, or client-specific requirements. In these situations, minor deviations from REST principles may be necessary to meet specific needs, ensuring that the API remains effective and user-friendly.
+
+For example:
+When Casasndra node operations are mapped to APIs, like decommission or repair, the tradeoff has been made in favor of readability and single-responsibility when compared to a purely RESTful design.
+
+Current design:
+PUT /api/v1/cassandra/operations/decommission
+PUT /api/v1/cassandra/operations/repair
+
+Potential RESTful alternative
+PUT /api/v1/cassandra/node
+{
+state: "DECOMMISSION" or "REPAIR"
+}

Review Comment:
   format the code



##########
CONTRIBUTING.md:
##########
@@ -101,7 +97,45 @@ components of each feature.
 
 ### <a name="new-apis"></a>Introducing New APIs
 
-An API is a `Route` in Vertx's terminology. To add a new API, we want to define the route.
+To add a new API to Cassandra Sidecar, we need to follow a proposal process and then implement the route. For detailed RESTful API design principles and standards, please refer to the [RESTful API Guidelines](#api-design) section.
+
+#### <a name="api-guidelines"></a>API Proposal Process
+
+We welcome contributions to improve the Cassandra Sidecar, especially in the form of new APIs that enhance operability, observability, and integration with Cassandra clusters. To ensure high-quality and maintainable additions, contributors are encouraged to follow the process outlined below:
+
+1. **Proposing API Designs**
+
+   Before implementing a new API or making a significant change to an existing one, contributors should submit a design proposal in the following manner:
+
+   * Propose the API spec in the JIRA ticket and additionally in a 1-pager (depending on the complexity of the proposal) in Google docs. This should align with the RESTful API Guidelines.

Review Comment:
   nit: google docs is too specific/limited. It is good, as long as the design doc is public accessible.



##########
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:
   - The HTTP **methods** (use the plural form)  
   - Why are http methods mentioned in the item 1? Should they be merged into item 2?
   - nit: add code marks for http methods 
   
   



##########
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.
+2. Use HTTP Methods to denote the action to be performed on the resource and HTTP Response codes to denote the outcome of the operation. For more details, refer to  Requests and Responses
+3. URI Naming Conventions
+   * Follow a consistent usage of plural nouns for resources. eg. /keyspaces/123
+   * Should be all lower case, with "-" as the word separator.
+   * Use Sub-resources for Hierarchical Relationships. eg. Orders by a user can be scoped as nested resource within users resource -   /users/{userId}/orders/{orderId}.
+4. Response Format
+   * Prefer to represent primitive types as corresponding types in JSON. eg.
+
+```json
+{
+"userId": 123,             // number
+"isActive": true,          // boolean
+"userName": "JohnDoe",     // string
+"createdDate": "2024-08-20T12:34:56Z" // string (for date-time)
+}
+```
+
+5. Pagination – do not return unbounded responses. Always ensure that the API responses are bounded to a reasonable default. eg. /users?page=2&limit=10

Review Comment:
   add code markers for `/users?page=2&limit=10`



##########
CONTRIBUTING.md:
##########
@@ -101,7 +97,45 @@ components of each feature.
 
 ### <a name="new-apis"></a>Introducing New APIs
 
-An API is a `Route` in Vertx's terminology. To add a new API, we want to define the route.
+To add a new API to Cassandra Sidecar, we need to follow a proposal process and then implement the route. For detailed RESTful API design principles and standards, please refer to the [RESTful API Guidelines](#api-design) section.
+
+#### <a name="api-guidelines"></a>API Proposal Process
+
+We welcome contributions to improve the Cassandra Sidecar, especially in the form of new APIs that enhance operability, observability, and integration with Cassandra clusters. To ensure high-quality and maintainable additions, contributors are encouraged to follow the process outlined below:
+
+1. **Proposing API Designs**
+
+   Before implementing a new API or making a significant change to an existing one, contributors should submit a design proposal in the following manner:
+
+   * Propose the API spec in the JIRA ticket and additionally in a 1-pager (depending on the complexity of the proposal) in Google docs. This should align with the RESTful API Guidelines.
+   * For proposals involving a group of APIs, the API spec proposal can be referenced in a [DISCUSS] thread in the mailing-list to get broader community feedback and iterate on the proposal.
+
+   Sample proposal in JIRA with API spec: https://issues.apache.org/jira/projects/CASSSIDECAR/issues/CASSSIDECAR-274

Review Comment:
   Use markdown's link format. 
   
   ```
   [CASSSIDECAR-274](https://issues.apache.org/jira/projects/CASSSIDECAR/issues/CASSSIDECAR-274)
   ```



##########
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.
+2. Use HTTP Methods to denote the action to be performed on the resource and HTTP Response codes to denote the outcome of the operation. For more details, refer to  Requests and Responses
+3. URI Naming Conventions
+   * Follow a consistent usage of plural nouns for resources. eg. /keyspaces/123

Review Comment:
   add code marks for `/keyspaces/123`



##########
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.
+2. Use HTTP Methods to denote the action to be performed on the resource and HTTP Response codes to denote the outcome of the operation. For more details, refer to  Requests and Responses
+3. URI Naming Conventions
+   * Follow a consistent usage of plural nouns for resources. eg. /keyspaces/123
+   * Should be all lower case, with "-" as the word separator.
+   * Use Sub-resources for Hierarchical Relationships. eg. Orders by a user can be scoped as nested resource within users resource -   /users/{userId}/orders/{orderId}.
+4. Response Format
+   * Prefer to represent primitive types as corresponding types in JSON. eg.
+
+```json
+{
+"userId": 123,             // number
+"isActive": true,          // boolean
+"userName": "JohnDoe",     // string
+"createdDate": "2024-08-20T12:34:56Z" // string (for date-time)
+}
+```
+
+5. Pagination – do not return unbounded responses. Always ensure that the API responses are bounded to a reasonable default. eg. /users?page=2&limit=10
+6. Filtering & Sorting – Support filtering and sorting where applicable.
+7. Versioning - APIs must use semantic versioning, with the major-version encoded into the URL. For more information, see Lifecycle.
+
+#### Exceptions
+
+There may be cases where adhering strictly to REST may not be practical, such as cases where the application behavior does not fit into the state-machine model, dealing with complex workflows, real-time communication, or client-specific requirements. In these situations, minor deviations from REST principles may be necessary to meet specific needs, ensuring that the API remains effective and user-friendly.
+
+For example:
+When Casasndra node operations are mapped to APIs, like decommission or repair, the tradeoff has been made in favor of readability and single-responsibility when compared to a purely RESTful design.

Review Comment:
   nit: just "~Casasndra~ ~node~ Cassandra operations" sounds clearer, and fixes the typo



##########
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.
+2. Use HTTP Methods to denote the action to be performed on the resource and HTTP Response codes to denote the outcome of the operation. For more details, refer to  Requests and Responses
+3. URI Naming Conventions
+   * Follow a consistent usage of plural nouns for resources. eg. /keyspaces/123
+   * Should be all lower case, with "-" as the word separator.
+   * Use Sub-resources for Hierarchical Relationships. eg. Orders by a user can be scoped as nested resource within users resource -   /users/{userId}/orders/{orderId}.
+4. Response Format
+   * Prefer to represent primitive types as corresponding types in JSON. eg.
+
+```json
+{
+"userId": 123,             // number
+"isActive": true,          // boolean
+"userName": "JohnDoe",     // string
+"createdDate": "2024-08-20T12:34:56Z" // string (for date-time)

Review Comment:
   add indentation



-- 
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: pr-unsubscribe@cassandra.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: pr-unsubscribe@cassandra.apache.org
For additional commands, e-mail: pr-help@cassandra.apache.org


Re: [PR] CASSSIDECAR-358 Adds API contribution and design guidelines [cassandra-sidecar]

Posted by "arjunashok (via GitHub)" <gi...@apache.org>.
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: pr-unsubscribe@cassandra.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: pr-unsubscribe@cassandra.apache.org
For additional commands, e-mail: pr-help@cassandra.apache.org


Re: [PR] CASSSIDECAR-358 Adds API contribution and design guidelines [cassandra-sidecar]

Posted by "yifan-c (via GitHub)" <gi...@apache.org>.
yifan-c merged PR #293:
URL: https://github.com/apache/cassandra-sidecar/pull/293


-- 
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: pr-unsubscribe@cassandra.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: pr-unsubscribe@cassandra.apache.org
For additional commands, e-mail: pr-help@cassandra.apache.org