Proposal: Removal of Namespace terminology in Data API

[jeffreyscarpenter]

Background
When we designed the Data API, we attempted to abstract many Cassandra-specific details to make the API simpler to use. Among other choices, we preserved the concept of a group of containers or tables, but decided to call it a namespace instead of a keyspace. There was discussion of removing the concept of a keyspace/namespace entirely but this would have caused other issues. Because of this, we’ve found ourselves adding additional complexity to the concept by having to call them out together, but explain there is no difference between the two creating unnecessary cognitive overload for developers.

This is made worse for Data API users in DataStax Astra by the fact that we create a “default_keyspace” in Astra but then refer to it as a namespace in the portal, which looks quite odd and is confusing to developers.

Proposal
The concept of a container for document collections remains, and is not something we want to try to abstract. Instead of trying to substitute a different term “namespace”, we will revert to using the Cassandra standard term “keyspace”. We will do this in a way that is backwards compatible and minimizes impact and developer confusion.

The following changes are recommended:

• Add keyspace operations to the API to parallel the namespace operations, and mark the namespace operations as deprecated.
  • FindNamespaces -> FindKeyspaces
  • CreateNamespace → CreateKeyspace
  • DropNamespace → DropKeyspace
  • Return a warning message in the response of the keyspace operations that indicates use of a deprecated command.
  • One way to do this in code: rename existing operations to their new names, add operations with the old names, marked as deprecated, which act as aliases to the new operations.
  • Make sure all metrics/logging reference new operation names. We do not want to capture metrics/logging for the old operation names.
  • Make sure swagger/OpenAPI marks old operation names as deprecated.
• (optional) refactor references in the Data API implementation (i.e. rename NamespaceCommand to KeyspaceCommand).
  • This is not super important, and note that we haven’t fully removed the “jsonapi” references even though the API is renamed to “data-api”.