You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@solr.apache.org by "gerlowskija (via GitHub)" <gi...@apache.org> on 2024/01/24 15:41:43 UTC
[PR] SOLR-15781: Document v2 API syntax conventions [solr]
gerlowskija opened a new pull request, #2219:
URL: https://github.com/apache/solr/pull/2219
https://issues.apache.org/jira/browse/SOLR-XXXXX
# Description
Currently, decisions around what our v2 API should look like are scattered across a large number of JIRA tickets, PR reviews, and spreadsheets. There's no one place giving an overview of the desired syntax (beyond perhaps the general guidance in SIP-16 to move towards "REST" where possible).
# Solution
This commit attempts to address this by introducing docs describing some of the conventions used in our v2 API.
Room for improvement remains: parameters conventions remain a big gap, as does sourcing to the original rationale behind many of these decisions. But this PR provides a place to build off of moving forward.
# Tests
N/A - doc change only.
# Checklist
Please review the following and check all that apply:
- [x] I have reviewed the guidelines for [How to Contribute](https://github.com/apache/solr/blob/main/CONTRIBUTING.md) and my code conforms to the standards described there to the best of my ability.
- [x] I have created a Jira issue and added the issue ID to my pull request title.
- [x] I have given Solr maintainers [access](https://help.github.com/en/articles/allowing-changes-to-a-pull-request-branch-created-from-a-fork) to contribute to my PR branch. (optional but recommended)
- [x] I have developed this patch against the `main` branch.
- [ ] I have run `./gradlew check`.
- [x] I have added documentation to the dev-docs.
--
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: issues-unsubscribe@solr.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org
Re: [PR] SOLR-15781: Document v2 API syntax conventions [solr]
Posted by "gerlowskija (via GitHub)" <gi...@apache.org>.
gerlowskija merged PR #2219:
URL: https://github.com/apache/solr/pull/2219
--
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: issues-unsubscribe@solr.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org
Re: [PR] SOLR-15781: Document v2 API syntax conventions [solr]
Posted by "gerlowskija (via GitHub)" <gi...@apache.org>.
gerlowskija commented on code in PR #2219:
URL: https://github.com/apache/solr/pull/2219#discussion_r1469894384
##########
dev-docs/v2-api-conventions.adoc:
##########
@@ -0,0 +1,76 @@
+== HTTP Paths
+
+Where possible, each v2 API is given an HTTP path that reflects the resource type and/or name most relevant to its functionality.
+Resource types are typically plural nouns such as "aliases", "collections", and "shards".
+Resource names are (typically user-provided) identifiers such as "myAlias", "techproducts", and "shard1".
+For example, `/api/collections` is the HTTP path used for all APIs concerned with collections generally, but that don't involve any one specific collection (e.g. listing all collections).
+APIs that concern themselves with a specific collection use the HTTP path `/api/collections/someCollectionName`.
+
+
+Resource types and names are arranged in the HTTP path such that each path segment is more specific, or "narrower", than the segment that came before.
+This "narrowing" also extends to resources that have an "is part of" or "contains" relationship to one another.
+In these cases all relevant resources and their types are included in the path, with the "contained" or "child" resource following its "parent".
+For example, since replicas always belong to a shard, and shards always belong to a collection, most v2 APIs pertaining to a specific replica use the HTTP path: `/api/collections/specificCollectionName/shards/specificShardName/replicas/specificReplicaName`.
+
+Following these guidelines has given us the following (non-exhaustive) list of v2 API paths, provided here to give a good sense of the paths currently in use and the logic underlying them.
+* `/api/aliases`
+* `/api/aliases/specificAliasName`
+* `/api/aliases/specificAliasName/properties`
+* `/api/aliases/specificAliasName/properties/specificPropertyName`
+* `/api/backups/specificBackupName`
+* `/api/backups/specificBackupName/versions`
+* `/api/backups/specificBackupName/versions/specificVersion`
+* `/api/cluster/nodes/specificNodeName/roles`
+* `/api/cluster/nodes/specificNodeName/roles/specificRoleName`
+* `/api/cluster/properties`
+* `/api/cluster/properties/specificPropertyName`
+* `/api/collections`
+* `/api/collections/specificCollName`
+* `/api/collections/specificCollName/properties`
+* `/api/collections/specificCollName/properties/specificPropertyName`
+* `/api/collections/specificcollName/shards`
+* `/api/collections/specificCollName/shards/specificShardName`
+* `/api/collections/specificCollName/shards/specificShardName/replicas`
+* `/api/collections/specificCollName/shards/specificShardName/replicas/specificReplicaName`
+* `/api/collections/specificCollName/shards/specificShardName/replicas/specificReplicaName/properties`
+* `/api/collections/specificCollName/shards/specificShardName/replicas/specificReplicaName/properties/specificPropertyName`
+* `/api/configsets`
+* `/api/configsets/specificConfigsetName`
+* `/api/cores`
+* `/api/cores/specificCoreName`
+* `/api/node`
+
+=== Unproxied APIs
+
+The last entry on the list above, `/api/node`, exhibits a bit of a special case.
+SolrCloud handles most requests as a distributed system, i.e. any request can be made to any node in the cluster and Solr will proxy or route the request internally in order to serve a response.
+But not all APIs work this way- some functionality is designed to only return data from the receiving node, such as `/api/node/key` which returns a cryptographic key specific to the receiving node.
+Solr will not proxy these requests.
+To represent this distinction the API design uses the idiosyncratic path `/api/node`, to help distinguish these from other node-related APIs.
+
+== HTTP Methods
+
+Where possible, HTTP methods (colloquially called 'verbs') are used semantically to distinguish between APIs available at the same path.
+For example, the API to delete a collection uses the `DELETE` HTTP method, as in `DELETE /api/collections/specificCollectionName`.
+The API to modify the collection uses the `PUT` HTTP method, as in `PUT /api/collections/specificCollectionName`.
+
+While the best effort is made to use HTTP methods semantically, the v2 API currently restricts itself to the better known HTTP methods: `GET`, `POST`, `PUT`, and `DELETE`.
+In some situations this leads us to eschew a more semantically appropriate verb due to its relative obscurity.
+The most significant example of this is the HTTP method `PATCH`, which according to the HTTP spec is used to indicate a partial update (i.e. a resource modification request which only provides the part to-be-modified).
+Solr's "modify collection" functionality uses partial update semantics, but the v2 API uses `PUT` instead of `PATCH` due to the relative obscurity of the latter.
+
+For use within the v2 API, the four "popular" HTTP methods have the following semantics and implications:
+
+* `GET` - used for non-mutating (i.e. "read only") requests. Most often used to list elements of a particular resource type, or fetch information about about a specific named resource.
+* `POST` - used for non-idempotent resource modifications.
+* `PUT` - used for idempotent resource modifications.
+* `DELETE` - Used to delete or cleanup resource
+
+== Exceptional Cases - "Command" APIs
Review Comment:
The "index" terminology is primarily a thing for documentation and for the code itself. It doesn't appear in e.g. the HTTP path for APIs or anything like that.
So I don't think we need to discuss anything like that here - though maybe you have something particular in mind?
--
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: issues-unsubscribe@solr.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org
Re: [PR] SOLR-15781: Document v2 API syntax conventions [solr]
Posted by "epugh (via GitHub)" <gi...@apache.org>.
epugh commented on code in PR #2219:
URL: https://github.com/apache/solr/pull/2219#discussion_r1465140437
##########
dev-docs/v2-api-conventions.adoc:
##########
@@ -0,0 +1,76 @@
+== HTTP Paths
+
+Where possible, each v2 API is given an HTTP path that reflects the resource type and/or name most relevant to its functionality.
+Resource types are typically plural nouns such as "aliases", "collections", and "shards".
+Resource names are (typically user-provided) identifiers such as "myAlias", "techproducts", and "shard1".
+For example, `/api/collections` is the HTTP path used for all APIs concerned with collections generally, but that don't involve any one specific collection (e.g. listing all collections).
+APIs that concern themselves with a specific collection use the HTTP path `/api/collections/someCollectionName`.
+
+
+Resource types and names are arranged in the HTTP path such that each path segment is more specific, or "narrower", than the segment that came before.
+This "narrowing" also extends to resources that have an "is part of" or "contains" relationship to one another.
+In these cases all relevant resources and their types are included in the path, with the "contained" or "child" resource following its "parent".
+For example, since replicas always belong to a shard, and shards always belong to a collection, most v2 APIs pertaining to a specific replica use the HTTP path: `/api/collections/specificCollectionName/shards/specificShardName/replicas/specificReplicaName`.
+
+Following these guidelines has given us the following (non-exhaustive) list of v2 API paths, provided here to give a good sense of the paths currently in use and the logic underlying them.
+* `/api/aliases`
+* `/api/aliases/specificAliasName`
+* `/api/aliases/specificAliasName/properties`
+* `/api/aliases/specificAliasName/properties/specificPropertyName`
+* `/api/backups/specificBackupName`
+* `/api/backups/specificBackupName/versions`
+* `/api/backups/specificBackupName/versions/specificVersion`
+* `/api/cluster/nodes/specificNodeName/roles`
+* `/api/cluster/nodes/specificNodeName/roles/specificRoleName`
+* `/api/cluster/properties`
+* `/api/cluster/properties/specificPropertyName`
+* `/api/collections`
+* `/api/collections/specificCollName`
+* `/api/collections/specificCollName/properties`
+* `/api/collections/specificCollName/properties/specificPropertyName`
+* `/api/collections/specificcollName/shards`
+* `/api/collections/specificCollName/shards/specificShardName`
+* `/api/collections/specificCollName/shards/specificShardName/replicas`
+* `/api/collections/specificCollName/shards/specificShardName/replicas/specificReplicaName`
+* `/api/collections/specificCollName/shards/specificShardName/replicas/specificReplicaName/properties`
+* `/api/collections/specificCollName/shards/specificShardName/replicas/specificReplicaName/properties/specificPropertyName`
+* `/api/configsets`
+* `/api/configsets/specificConfigsetName`
+* `/api/cores`
+* `/api/cores/specificCoreName`
+* `/api/node`
+
+=== Unproxied APIs
+
+The last entry on the list above, `/api/node`, exhibits a bit of a special case.
+SolrCloud handles most requests as a distributed system, i.e. any request can be made to any node in the cluster and Solr will proxy or route the request internally in order to serve a response.
+But not all APIs work this way- some functionality is designed to only return data from the receiving node, such as `/api/node/key` which returns a cryptographic key specific to the receiving node.
+Solr will not proxy these requests.
+To represent this distinction the API design uses the idiosyncratic path `/api/node`, to help distinguish these from other node-related APIs.
+
+== HTTP Methods
+
+Where possible, HTTP methods (colloquially called 'verbs') are used semantically to distinguish between APIs available at the same path.
+For example, the API to delete a collection uses the `DELETE` HTTP method, as in `DELETE /api/collections/specificCollectionName`.
+The API to modify the collection uses the `PUT` HTTP method, as in `PUT /api/collections/specificCollectionName`.
+
+While the best effort is made to use HTTP methods semantically, the v2 API currently restricts itself to the better known HTTP methods: `GET`, `POST`, `PUT`, and `DELETE`.
+In some situations this leads us to eschew a more semantically appropriate verb due to its relative obscurity.
+The most significant example of this is the HTTP method `PATCH`, which according to the HTTP spec is used to indicate a partial update (i.e. a resource modification request which only provides the part to-be-modified).
+Solr's "modify collection" functionality uses partial update semantics, but the v2 API uses `PUT` instead of `PATCH` due to the relative obscurity of the latter.
+
+For use within the v2 API, the four "popular" HTTP methods have the following semantics and implications:
+
+* `GET` - used for non-mutating (i.e. "read only") requests. Most often used to list elements of a particular resource type, or fetch information about about a specific named resource.
+* `POST` - used for non-idempotent resource modifications.
+* `PUT` - used for idempotent resource modifications.
+* `DELETE` - Used to delete or cleanup resource
+
+== Exceptional Cases - "Command" APIs
Review Comment:
Do we need to also call out the "index" special case, of being a collection or core in this doc?
##########
dev-docs/apis.adoc:
##########
@@ -51,27 +51,28 @@ Separating the API "definition" and "implementation" in this way allows us to on
Writing a new v2 API may appear daunting, but additions in reality are actually pretty simple:
-1. *Create POJO ("Plain Old Java Object") classes as needed to represent the API's request and response*:
+1. *Agree on Endpoint Syntax*: Before implementing, developers should generate consensus around what the new API will look like. General guidelines and conventions for the v2 API syntax are described <<v2-api-conventions.adoc,here>>.
Review Comment:
In markdown you can do:
```
1. First item
1. Second item
1. Third item
1. Fourth item
```
Does that work in adoc? would that make life easier?
--
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: issues-unsubscribe@solr.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org
Re: [PR] SOLR-15781: Document v2 API syntax conventions [solr]
Posted by "gerlowskija (via GitHub)" <gi...@apache.org>.
gerlowskija commented on code in PR #2219:
URL: https://github.com/apache/solr/pull/2219#discussion_r1469903877
##########
dev-docs/apis.adoc:
##########
@@ -51,27 +51,28 @@ Separating the API "definition" and "implementation" in this way allows us to on
Writing a new v2 API may appear daunting, but additions in reality are actually pretty simple:
-1. *Create POJO ("Plain Old Java Object") classes as needed to represent the API's request and response*:
+1. *Agree on Endpoint Syntax*: Before implementing, developers should generate consensus around what the new API will look like. General guidelines and conventions for the v2 API syntax are described <<v2-api-conventions.adoc,here>>.
Review Comment:
It definitely works in adoc. The question I'd ask though is whether Github is smart enough to do it as well when it's previewing these asciidoc files.
That's the main way we expect these to be consumed, right? Through the Github UI? (i.e. we don't actually build these asciidoc files into any thing analogous to the ref-guide?)
I'll push the change and see how Github handles it; if GH doesn't do-the-right-thing I'll revert.
--
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: issues-unsubscribe@solr.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org
Re: [PR] SOLR-15781: Document v2 API syntax conventions [solr]
Posted by "gerlowskija (via GitHub)" <gi...@apache.org>.
gerlowskija commented on code in PR #2219:
URL: https://github.com/apache/solr/pull/2219#discussion_r1469907912
##########
dev-docs/apis.adoc:
##########
@@ -51,27 +51,28 @@ Separating the API "definition" and "implementation" in this way allows us to on
Writing a new v2 API may appear daunting, but additions in reality are actually pretty simple:
-1. *Create POJO ("Plain Old Java Object") classes as needed to represent the API's request and response*:
+1. *Agree on Endpoint Syntax*: Before implementing, developers should generate consensus around what the new API will look like. General guidelines and conventions for the v2 API syntax are described <<v2-api-conventions.adoc,here>>.
Review Comment:
Looks like GH does do the right thing 👍
--
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: issues-unsubscribe@solr.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org