From 3b0e42866fd98dc0364f31c2f4492956f97a4760 Mon Sep 17 00:00:00 2001
From: Theresa Kamerman <theresa.kamerman@jpl.nasa.gov>
Date: Mon, 16 Oct 2023 09:41:54 -0700
Subject: [PATCH] Cleanup extensions API docs

- Use the specified query variables instead of inlining
- Refine `InsertExtension` to use the `_one` form instead of the "many" form
- Remove the "advanced" tag from the API docs
---
 docs/api/examples/advanced-extensions.mdx | 54 ++++++++++++++++-------
 sidebars.js                               |  2 +-
 2 files changed, 39 insertions(+), 17 deletions(-)

diff --git a/docs/api/examples/advanced-extensions.mdx b/docs/api/examples/advanced-extensions.mdx
index d085e25..2567a3f 100644
--- a/docs/api/examples/advanced-extensions.mdx
+++ b/docs/api/examples/advanced-extensions.mdx
@@ -1,36 +1,58 @@
-# Advanced - Extensions
+# Extensions
 
-## Creating an Extension
+## Adding an Extension
 
 ```graphql
-mutation InsertExtensions($object: extensions_insert_input!) {
-  insert_extensions(
-    objects: { description: "", label: "My External Application", url: "https://externalapp/api/test" }
-  ) {
-    returning {
-      id
-    }
+mutation InsertExtension($extension: extensions_insert_input!) {
+  insert_extensions_one(object: $extension) {
+    id
+    label
+    url
+    description
   }
 }
 ```
 
-## Creating an Extension Role
+Below is an example query variable that creates an extension called "My External Application".
+
+```json
+{
+  "extension": {
+    "label": "My External Application",
+    "url": "https://externalapp/api/test",
+    "description": "An application that exists outside of Aerie."
+  }
+}
+```
 
-This is an example query that would allow the `viewer` role the ability to execute the extension with id `1`. Only defined roles will be able to call the extension through the UI.
+## Permitting Roles to run Extensions
 
 ```graphql
-mutation InsertExtensionRoles($object: extension_roles_insert_input!) {
-  insert_extension_roles(objects: { extension_id: 1, role: "viewer" }) {
+mutation InsertExtensionRoles($roles: [extension_roles_insert_input!]! ) {
+  insert_extension_roles(objects: $roles) {
     returning {
-      id
+      extension {
+        id
+        label
+      }
+      role
     }
   }
 }
 ```
 
-## Deleting an Extension
+Below is an example query variable that grants the `aerie_admin` and `user` roles to run the extension with an ID of 1.
 
-The following query will delete an extension and cascade to delete any assigned roles for that extension as well.
+```json
+{
+  "roles": [
+    { "extension_id": 1, "role": "aerie_admin" },
+    { "extension_id": 1, "role": "user" }
+  ]
+}
+```
+
+## Deleting an Extension
 
 ```graphql
 mutation DeleteExtension($extension_id: Int!) {
diff --git a/sidebars.js b/sidebars.js
index 1825a6e..c727710 100644
--- a/sidebars.js
+++ b/sidebars.js
@@ -22,13 +22,13 @@ const sidebars = {
           items: [
             'api/examples/planning/collaboration',
             'api/examples/planning/anchors',
-            'api/examples/advanced-extensions',
           ],
         },
         'api/examples/simulation',
         'api/examples/constraints',
         'api/examples/scheduling',
         'api/examples/activity-presets',
+        'api/examples/advanced-extensions',
       ],
     },
   ],