(DOCSP-38560): Edge Server Admin API Endpoint Documentation #741

dacharyc · 2024-04-19T17:53:28Z

Pull Request Info

Jira ticket: https://jira.mongodb.org/browse/DOCSP-38560

Admin API: New Edge Server endpoints:

A few endpoints aren't testable right now because of bugs or because they're not yet in prod, so adding these todo items which should carry over to the feature branch:

TODOS for Feature Branch:

Test Delete API
Test Regenerate API
Test Rename API
Populate data for Get Edge Server Info/metrics object

Release Notes

Admin API
- New Edge Server endpoints:
  - List Edge Server instances
  - Get information about an Edge Server instance
  - Create an Edge Server instance
  - Delete an Edge Server instance
  - Regenerate an Edge Server registration key
  - Rename an Edge Server instance

Review Guidelines

REVIEWING.md

source/openapi-admin-v3.yaml

sudssm · 2024-04-21T16:37:22Z

source/openapi-admin-v3.yaml

+          example: 6622b8f5118368b943d228a9
+          description: |-
+            The unique identifier of the Edge Server instance, of type 
+            ObjectId, as a string. You can use this identifier when configuring


actually, you wouldn't use the edge server ID to configure permissions; you'd use it to delete/ update the edge server. you'duse the user id to configure perms

source/openapi-admin-v3.yaml

sudssm · 2024-04-21T16:37:52Z

source/openapi-admin-v3.yaml

+          description: |-
+            Save this information. When you install the Edge Server code on the
+            host, enter this registration key. The Edge Server exchanges this 
+            for an API Key that it uses to authenticate with Atlas.


worth adding that it can only be used once?

sudssm · 2024-04-21T16:38:53Z

source/openapi-admin-v3.yaml

+            - "unregistered"
+          description: |-
+            The current status of the Edge Server instance.
+        hostname:


this is not going to be populated for the foreseeable future; we should just omit it

sudssm · 2024-04-21T16:40:32Z

source/openapi-admin-v3.yaml

+      tags:
+        - edge-server
+      operationId: adminRegenerateEdgeServerRegistrationKey
+      summary: Regenerate Edge Server registration key


we should update all instances of "registration key" with "registration token". except, unfortunately, the endpoint itself which we will keep as-is for now

cbullinger

current draft lgtm. happy to re-review once you apply tech feedback or after additional updates 👍

cbullinger · 2024-04-22T13:05:57Z

source/openapi-admin-v3.yaml

+                  name:
+                    type: string
+                    example: Edge-Store-42
+                    description: A human-readable name for the Edge Server instance.


Suggested change

description: A human-readable name for the Edge Server instance.

description: A unique human-readable name for the Edge Server instance.

cbullinger · 2024-04-22T13:13:15Z

source/openapi-admin-v3.yaml

+        - edge-server
+      operationId: adminCreateEdgeServerInstance
+      summary: Create an Edge Server instance
+      description: Create a new Edge Server instance.


Do we want to mention any of the registration process here? e.g.

Suggested change

description: Create a new Edge Server instance.

description: Create a new Edge Server instance. The response returns a registration key (token?) that you use to authenticate Edge Server on the host.

cbullinger · 2024-04-22T13:14:32Z

source/openapi-admin-v3.yaml

+                    description: A human-readable name for the Edge Server instance.
+                    required: true
+      responses:
+        "201":


I know we're crunched for time on this, but in general, should we be doc'ing the errors too?

docs-builder-bot · 2024-04-26T16:45:06Z

✨ Staging URL: https://preview-mongodbmongodb.gatsbyjs.io/atlas-app-services/edge-server-public-preview-docs/

🪵 Logs

job log: 9b8c1d4e260c917f467645de43a6fc0b295c1ec7

* Edge Server: Add findAndModify command (#726) * Add findAndModify command * Apply review suggestion Co-authored-by: cbullinger <115956901+cbullinger@users.noreply.github.com> --------- Co-authored-by: cbullinger <115956901+cbullinger@users.noreply.github.com> * (DOCSP-38851): Add a Manage Edge Servers page (#728) * Draft Manage Edge Servers page * Grammatical and other minor fixes * Add info about Edge Server using Device Sync * Formatting fixes * Refactor enable Device Sync callout to include * Add info about updating a data model * Remove placeholders on Configure page in favor of other PR * Remove 'Register' details as this occurs during configuration * Add details about supported authentication providers * Incorporate tech review feedback * Clarify Edge Server service, instance language, grammar and typo fixes * Fix wireprotocol to Wire Protocol * Incorporate review feedback * Change 'MongoDB URI' reference to 'Driver' * Clarify details about _id field type * (DOCSP-38550): Update Edge Server landing page for Public Preview (#739) * Update Edge Server landing page for public preview * Add meta description * Apply suggestions from review Co-authored-by: cbullinger <115956901+cbullinger@users.noreply.github.com> * Add info about the template app to the CTA --------- Co-authored-by: cbullinger <115956901+cbullinger@users.noreply.github.com> * (DOCSP-38852): Update the 'Configure' page for Public Preview (#733) * Update the 'Configure' page for Public Preview * Clarify and add details, improve table styling in procedure * More details and table formatting fixes * Incorporate review feedback * Add table widths to fix formatting * Incorporate more review feedback * Incorporate tech review feedback * Apply tech review feedback * Clarify linked data source * Simplify collection/schema in the example copy * (DOCSP-38553): Update the 'Connect' page for Public Preview (#735) * Update the 'Connect' page for Public Preview * Product naming and grammar fixes * Update server/instance/service language per discussion * Incorporate review feedback * Incorporate tech review feedback and test connecting * Remove the 'Supported Auth Providers' section * Apply review suggestions Co-authored-by: cbullinger <115956901+cbullinger@users.noreply.github.com> * Incorporate review feedback --------- Co-authored-by: cbullinger <115956901+cbullinger@users.noreply.github.com> * Note that num_local_clients does not include Wire Protocol connections * (DOCSP-38875): Edge Server Permissions Guide (#745) * Draft Edge Server permissions page * Reverse the order of client permissions to match example image * Rename section and update refs to match * Wording clarifications * Apply suggestions from review Co-authored-by: cbullinger <115956901+cbullinger@users.noreply.github.com> * Move explanations above examples * Apply tech review feedback * Fix snippet highlighting range --------- Co-authored-by: cbullinger <115956901+cbullinger@users.noreply.github.com> * (DOCSP-38560): Edge Server Admin API Endpoint Documentation (#741) * Initial draft of new Edge endpoints * Remove endpoints to try to get docs to build * Fix nesting maybe * Add type for Get response schema * Add examples * Add info about user_id, status enum options * Add examples for combined schema * Remove inline examples * Add Edge Server tag * Change 'examples' to 'example' * Move examples to schema definition * Add examples back to inline base definition * Move base example to schema level instead of inline * Remove base object and move definitions into separate objects * Minor tweaks to descriptions and required fields * Updates based on API code * Incorporate review feedback * Note that 'hostname' is not currently populated * Update HTTP responses for newly-tested endpoints * Wrap date times in quotes * Add metrics details * Fix build error * Remove 'placeholder' boilerplate * Update example query to a more general, representative example * Update the correct query example * (DOCSP-38554): Add a Monitor Edge Server page (#748) * WIP draft monitor page * Populate log details * Adjust table spacing * Adjust table spacing * Adjust table spacing * Adjust table spacing * Adjust table spacing * Apply suggestions from review Co-authored-by: cbullinger <115956901+cbullinger@users.noreply.github.com> * Add BOOTSTRAPPING to the status options * Move table contents over by one space to fix formatting issue * Change widths to adjust spacing --------- Co-authored-by: cbullinger <115956901+cbullinger@users.noreply.github.com> * (DOCSP-39016): Update `edgectl` details for `init`, `query` and `profile` (#747) * Update edgectl details for release * Fix unexpected intent error * Update the cycle registration token flag * Apply review feedback * (DOCSP-38863): Address TODOs and placeholders to prepare Feature Branch for merging (#749) * Populate Admin API details in procedures on the Manage page * Populate placeholder refs to Metrics and Logs on Manage page * Fix title underline length issues on Permissions page * Populate Admin API endpoint placeholder on Permissions page * Populate Admin API placeholders on Monitor page * Add info about adding Edge Servers to a Device Sync App * Add detail about stopping and starting an instance to add a new collection * Apply suggestions from review Co-authored-by: lindseymoore <71525840+lindseymoore@users.noreply.github.com> --------- Co-authored-by: lindseymoore <71525840+lindseymoore@users.noreply.github.com> * Apply suggestions from review Co-authored-by: cbullinger <115956901+cbullinger@users.noreply.github.com> * Be more explicit in edgectl bool flags and remove unneeded flag * Fix missing Admin API placeholders * Add boostrapping state for Edge Server status in the UI * Capitalize Wire Protocol * Replace generic Data Services procedure with specific procedure --------- Co-authored-by: cbullinger <115956901+cbullinger@users.noreply.github.com> Co-authored-by: lindseymoore <71525840+lindseymoore@users.noreply.github.com>

* Edge Server: Add findAndModify command (mongodb#726) * Add findAndModify command * Apply review suggestion Co-authored-by: cbullinger <115956901+cbullinger@users.noreply.github.com> --------- Co-authored-by: cbullinger <115956901+cbullinger@users.noreply.github.com> * (DOCSP-38851): Add a Manage Edge Servers page (mongodb#728) * Draft Manage Edge Servers page * Grammatical and other minor fixes * Add info about Edge Server using Device Sync * Formatting fixes * Refactor enable Device Sync callout to include * Add info about updating a data model * Remove placeholders on Configure page in favor of other PR * Remove 'Register' details as this occurs during configuration * Add details about supported authentication providers * Incorporate tech review feedback * Clarify Edge Server service, instance language, grammar and typo fixes * Fix wireprotocol to Wire Protocol * Incorporate review feedback * Change 'MongoDB URI' reference to 'Driver' * Clarify details about _id field type * (DOCSP-38550): Update Edge Server landing page for Public Preview (mongodb#739) * Update Edge Server landing page for public preview * Add meta description * Apply suggestions from review Co-authored-by: cbullinger <115956901+cbullinger@users.noreply.github.com> * Add info about the template app to the CTA --------- Co-authored-by: cbullinger <115956901+cbullinger@users.noreply.github.com> * (DOCSP-38852): Update the 'Configure' page for Public Preview (mongodb#733) * Update the 'Configure' page for Public Preview * Clarify and add details, improve table styling in procedure * More details and table formatting fixes * Incorporate review feedback * Add table widths to fix formatting * Incorporate more review feedback * Incorporate tech review feedback * Apply tech review feedback * Clarify linked data source * Simplify collection/schema in the example copy * (DOCSP-38553): Update the 'Connect' page for Public Preview (mongodb#735) * Update the 'Connect' page for Public Preview * Product naming and grammar fixes * Update server/instance/service language per discussion * Incorporate review feedback * Incorporate tech review feedback and test connecting * Remove the 'Supported Auth Providers' section * Apply review suggestions Co-authored-by: cbullinger <115956901+cbullinger@users.noreply.github.com> * Incorporate review feedback --------- Co-authored-by: cbullinger <115956901+cbullinger@users.noreply.github.com> * Note that num_local_clients does not include Wire Protocol connections * (DOCSP-38875): Edge Server Permissions Guide (mongodb#745) * Draft Edge Server permissions page * Reverse the order of client permissions to match example image * Rename section and update refs to match * Wording clarifications * Apply suggestions from review Co-authored-by: cbullinger <115956901+cbullinger@users.noreply.github.com> * Move explanations above examples * Apply tech review feedback * Fix snippet highlighting range --------- Co-authored-by: cbullinger <115956901+cbullinger@users.noreply.github.com> * (DOCSP-38560): Edge Server Admin API Endpoint Documentation (mongodb#741) * Initial draft of new Edge endpoints * Remove endpoints to try to get docs to build * Fix nesting maybe * Add type for Get response schema * Add examples * Add info about user_id, status enum options * Add examples for combined schema * Remove inline examples * Add Edge Server tag * Change 'examples' to 'example' * Move examples to schema definition * Add examples back to inline base definition * Move base example to schema level instead of inline * Remove base object and move definitions into separate objects * Minor tweaks to descriptions and required fields * Updates based on API code * Incorporate review feedback * Note that 'hostname' is not currently populated * Update HTTP responses for newly-tested endpoints * Wrap date times in quotes * Add metrics details * Fix build error * Remove 'placeholder' boilerplate * Update example query to a more general, representative example * Update the correct query example * (DOCSP-38554): Add a Monitor Edge Server page (mongodb#748) * WIP draft monitor page * Populate log details * Adjust table spacing * Adjust table spacing * Adjust table spacing * Adjust table spacing * Adjust table spacing * Apply suggestions from review Co-authored-by: cbullinger <115956901+cbullinger@users.noreply.github.com> * Add BOOTSTRAPPING to the status options * Move table contents over by one space to fix formatting issue * Change widths to adjust spacing --------- Co-authored-by: cbullinger <115956901+cbullinger@users.noreply.github.com> * (DOCSP-39016): Update `edgectl` details for `init`, `query` and `profile` (mongodb#747) * Update edgectl details for release * Fix unexpected intent error * Update the cycle registration token flag * Apply review feedback * (DOCSP-38863): Address TODOs and placeholders to prepare Feature Branch for merging (mongodb#749) * Populate Admin API details in procedures on the Manage page * Populate placeholder refs to Metrics and Logs on Manage page * Fix title underline length issues on Permissions page * Populate Admin API endpoint placeholder on Permissions page * Populate Admin API placeholders on Monitor page * Add info about adding Edge Servers to a Device Sync App * Add detail about stopping and starting an instance to add a new collection * Apply suggestions from review Co-authored-by: lindseymoore <71525840+lindseymoore@users.noreply.github.com> --------- Co-authored-by: lindseymoore <71525840+lindseymoore@users.noreply.github.com> * Apply suggestions from review Co-authored-by: cbullinger <115956901+cbullinger@users.noreply.github.com> * Be more explicit in edgectl bool flags and remove unneeded flag * Fix missing Admin API placeholders * Add boostrapping state for Edge Server status in the UI * Capitalize Wire Protocol * Replace generic Data Services procedure with specific procedure --------- Co-authored-by: cbullinger <115956901+cbullinger@users.noreply.github.com> Co-authored-by: lindseymoore <71525840+lindseymoore@users.noreply.github.com>

Initial draft of new Edge endpoints

c9a62c8

dacharyc added the merge to feature branch Unreleased feature - do not merge to Master label Apr 19, 2024

Remove endpoints to try to get docs to build

3754ac4

dacharyc changed the title ~~(Docsp 38560): Edge Server Admin API Endpoint Documentation~~ (DOCSP-38560): Edge Server Admin API Endpoint Documentation Apr 19, 2024

dacharyc added 14 commits April 19, 2024 14:20

Fix nesting maybe

0cae44a

Add type for Get response schema

bd3dcc4

Add examples

13d47c8

Add info about user_id, status enum options

e427899

Add examples for combined schema

3579d4a

Remove inline examples

87fd1e5

Add Edge Server tag

e14dac6

Change 'examples' to 'example'

b449e31

Move examples to schema definition

ec8f151

Add examples back to inline base definition

9adf32b

Move base example to schema level instead of inline

a3aafae

Remove base object and move definitions into separate objects

4cce167

Minor tweaks to descriptions and required fields

09e6758

Updates based on API code

3eb3659

dacharyc requested review from sudssm and rukumar333 April 19, 2024 21:26

sudssm approved these changes Apr 21, 2024

View reviewed changes

cbullinger approved these changes Apr 22, 2024

View reviewed changes

dacharyc added 2 commits April 22, 2024 18:28

Incorporate review feedback

fa8adc5

Note that 'hostname' is not currently populated

4df4880

dacharyc force-pushed the DOCSP-38560 branch from b8748bd to 4df4880 Compare April 22, 2024 22:41

Update HTTP responses for newly-tested endpoints

ae95986

dacharyc force-pushed the DOCSP-38560 branch from e20e9d0 to ae95986 Compare April 25, 2024 20:56

dacharyc added 3 commits April 25, 2024 19:03

Wrap date times in quotes

2fc72a2

Add metrics details

32fcc46

Fix build error

3fde05e

dacharyc added 3 commits April 26, 2024 12:27

Remove 'placeholder' boilerplate

378af65

Update example query to a more general, representative example

ca1dd58

Update the correct query example

72683ec

dacharyc merged commit 9b8c1d4 into mongodb:edge-server-public-preview-docs Apr 26, 2024
5 checks passed

dacharyc deleted the DOCSP-38560 branch April 26, 2024 16:42

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

(DOCSP-38560): Edge Server Admin API Endpoint Documentation #741

(DOCSP-38560): Edge Server Admin API Endpoint Documentation #741

dacharyc commented Apr 19, 2024 •

edited

Loading

sudssm Apr 21, 2024

sudssm Apr 21, 2024

sudssm Apr 21, 2024

sudssm Apr 21, 2024

cbullinger left a comment

cbullinger Apr 22, 2024

cbullinger Apr 22, 2024

cbullinger Apr 22, 2024

docs-builder-bot commented Apr 26, 2024

	description: A human-readable name for the Edge Server instance.
	description: A unique human-readable name for the Edge Server instance.

	description: Create a new Edge Server instance.
	description: Create a new Edge Server instance. The response returns a registration key (token?) that you use to authenticate Edge Server on the host.

(DOCSP-38560): Edge Server Admin API Endpoint Documentation #741

(DOCSP-38560): Edge Server Admin API Endpoint Documentation #741

Conversation

dacharyc commented Apr 19, 2024 • edited Loading

Pull Request Info

Release Notes

Review Guidelines

sudssm Apr 21, 2024

Choose a reason for hiding this comment

sudssm Apr 21, 2024

Choose a reason for hiding this comment

sudssm Apr 21, 2024

Choose a reason for hiding this comment

sudssm Apr 21, 2024

Choose a reason for hiding this comment

cbullinger left a comment

Choose a reason for hiding this comment

cbullinger Apr 22, 2024

Choose a reason for hiding this comment

cbullinger Apr 22, 2024

Choose a reason for hiding this comment

cbullinger Apr 22, 2024

Choose a reason for hiding this comment

docs-builder-bot commented Apr 26, 2024

🪵 Logs

dacharyc commented Apr 19, 2024 •

edited

Loading