From b4a962ffe85600bef2687b7c6f6286b89b723a12 Mon Sep 17 00:00:00 2001 From: "Adam H. Leventhal" Date: Wed, 6 Jul 2022 16:18:44 -0700 Subject: [PATCH 1/2] update entrypoint naming doc comment --- nexus/src/external_api/http_entrypoints.rs | 31 +++++++++++----------- 1 file changed, 16 insertions(+), 15 deletions(-) diff --git a/nexus/src/external_api/http_entrypoints.rs b/nexus/src/external_api/http_entrypoints.rs index 54d7ada148..66cea278bd 100644 --- a/nexus/src/external_api/http_entrypoints.rs +++ b/nexus/src/external_api/http_entrypoints.rs @@ -253,25 +253,26 @@ pub fn external_api() -> NexusApiDescription { // DELETE /organizations/{org_name} (delete a organization in the collection) // PUT /organizations/{org_name} (update a organization in the collection) // -// There's a naming convention for the functions that implement these API entry -// points. When operating on the collection itself, we use: +// We pick a name for the function that implements a given API entrypoint +// based on how we expect it to appear in the CLI subcommand hierarchy. For +// example: // -// {collection_path}_{verb} +// GET /organizations -> organization_list() +// POST /organizations -> organization_create() +// GET /organizations/{org_name} -> organization_view() +// DELETE /organizations/{org_name} -> organization_delete() +// PUT /organizations/{org_name} -> organization_update() // -// For examples: +// Note that the path typically uses the entity's plural form while the +// function name uses its singular. // -// GET /organizations -> organizations_get() -// POST /organizations -> organizations_post() +// Operations beyond list, create, view, delete, and update should use a +// descriptive noun or verb, again bearing in mind that this will be +// transcribed into the CLI: // -// For operations on items within the collection, we use: -// -// {collection_path}_{verb}_{object} -// -// For examples: -// -// DELETE /organizations/{org_name} -> organizations_delete_organization() -// GET /organizations/{org_name} -> organizations_get_organization() -// PUT /organizations/{org_name} -> organizations_put_organization() +// POST -> instance_reboot +// POST -> instance_stop +// GET -> instance_serial_console // // Note that these function names end up in generated OpenAPI spec as the // operationId for each endpoint, and therefore represent a contract with From 5f9e7ccb15bd061f432f8b61669a94353e9115d8 Mon Sep 17 00:00:00 2001 From: Adam Leventhal Date: Wed, 6 Jul 2022 16:28:03 -0700 Subject: [PATCH 2/2] Update nexus/src/external_api/http_entrypoints.rs Co-authored-by: Justin Bennett --- nexus/src/external_api/http_entrypoints.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/nexus/src/external_api/http_entrypoints.rs b/nexus/src/external_api/http_entrypoints.rs index 66cea278bd..e5ec80ed57 100644 --- a/nexus/src/external_api/http_entrypoints.rs +++ b/nexus/src/external_api/http_entrypoints.rs @@ -268,7 +268,7 @@ pub fn external_api() -> NexusApiDescription { // // Operations beyond list, create, view, delete, and update should use a // descriptive noun or verb, again bearing in mind that this will be -// transcribed into the CLI: +// transcribed into the CLI and SDKs: // // POST -> instance_reboot // POST -> instance_stop