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: [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]
