From b2317a00c325b2c137dd3a913ebefa9ff56a9f1b Mon Sep 17 00:00:00 2001 From: Michael Morran <67967136+mikemorran@users.noreply.github.com> Date: Thu, 16 Feb 2023 10:45:03 -0600 Subject: [PATCH 1/5] Update API.md with correction and new info Corrections: 1. Note about alpha testing removing note that users cannot create their own tokens. New Info: 1. Line about where to generate tokens. 2. Write rooms with info about customizable room features taken from graphQL schema in room_types.ex --- guides/api.md | 26 ++++++++++++++++++++++++-- 1 file changed, 24 insertions(+), 2 deletions(-) diff --git a/guides/api.md b/guides/api.md index f8e7f1502..89c71e6c7 100644 --- a/guides/api.md +++ b/guides/api.md @@ -1,7 +1,7 @@ # Hubs Server API Reticulum includes a [GraphQL](https://graphql.org/) API that grants programmatic access to server resources. -Note: This API is currently in alpha testing and is not yet available for use. (Users cannot generate API Access Tokens.) +Note: This API is currently in alpha testing and will likely experience frequent updates. ## Accessing the API Hubs Cloud administrators can enable or disable the API by toggling `App Settings > Features > Public API Access` in the admin panel. @@ -13,7 +13,9 @@ You must attach an API Access Token with each request. To attach an API Access Token to a request, add an `HTTP` header named `Authorization` with value `Bearer: `. -### API Access Token Types +### API Access Token Generation and Types +API Token can be generated and revoked though an interface located at `/tokens`. + There are two types of API Access Tokens: - `:account` tokens act on behalf of a specific user - `:app` tokens act on behalf of the Hubs Cloud itself @@ -28,6 +30,26 @@ Each API Access Token specifies its `scopes`. Scopes allow a token to be used to Scopes, actions, and token types are expected to expand over time. +## Write_Rooms +The following parameters can be written to individual rooms on `createRoom` or `updateRoom`. +`name` _str_ - The room name. +`description` _str_ - A description of the room. +`roomSize` _str_ - The number of non-admin participants allowed into the room from the lobby at any given time. +`sceneId` _str_ - The seven character id of the scene hosted on the server. +`sceneUrl` _str_ - A hosted asset to be used as the scene. Frequently used for specifying .glb files as scenes. +`memberPermissions` _map_ - A map of the permissions non-admin participants should have in the room. + `spawnAndMoveMedia` _bool_ - Allow non-admin participants to spawn and move media. + `spawnCamera` _bool_ - Allow non-admin participants to spawn in-game cameras. + `spawnDrawing` _bool_ - Allow non-admin participants to draw with a pen. + `pinObjects` _bool_ - Allow non-admin participants to pin media to the room. + `spawnEmoji` _bool_ - Allow non-admin participants to spawn emoji. + `fly` _bool_ - Allow non-admin participants to toggle fly mode. + `voiceChat` _bool_ - Allow non-admin participants to use the voice chat. + `textChat` _bool_ - Allow non-admin participants to use the text chat. +`user_data` _map_ - Arbitrary json data associated with this room + +See [room_types.ex](../lib/ret_web/schema/room_types.ex) for full GraphQL Schema. + ## Examples Reticulum ships with [GraphiQL](https://github.com/graphql/graphiql/tree/main/packages/graphiql#graphiql), a graphical, interactive, in-browser GraphQL IDE that makes it easier to test and learn the API. It can be accessed by navigating to `/api/v2_alpha/graphiql`. From a35844c383d66af89f5955436214eabfe4310862 Mon Sep 17 00:00:00 2001 From: Michael Morran <67967136+mikemorran@users.noreply.github.com> Date: Thu, 16 Feb 2023 10:52:11 -0600 Subject: [PATCH 2/5] Update api.md --- guides/api.md | 30 +++++++++++++++--------------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/guides/api.md b/guides/api.md index 89c71e6c7..d87b575f2 100644 --- a/guides/api.md +++ b/guides/api.md @@ -32,21 +32,21 @@ Scopes, actions, and token types are expected to expand over time. ## Write_Rooms The following parameters can be written to individual rooms on `createRoom` or `updateRoom`. -`name` _str_ - The room name. -`description` _str_ - A description of the room. -`roomSize` _str_ - The number of non-admin participants allowed into the room from the lobby at any given time. -`sceneId` _str_ - The seven character id of the scene hosted on the server. -`sceneUrl` _str_ - A hosted asset to be used as the scene. Frequently used for specifying .glb files as scenes. -`memberPermissions` _map_ - A map of the permissions non-admin participants should have in the room. - `spawnAndMoveMedia` _bool_ - Allow non-admin participants to spawn and move media. - `spawnCamera` _bool_ - Allow non-admin participants to spawn in-game cameras. - `spawnDrawing` _bool_ - Allow non-admin participants to draw with a pen. - `pinObjects` _bool_ - Allow non-admin participants to pin media to the room. - `spawnEmoji` _bool_ - Allow non-admin participants to spawn emoji. - `fly` _bool_ - Allow non-admin participants to toggle fly mode. - `voiceChat` _bool_ - Allow non-admin participants to use the voice chat. - `textChat` _bool_ - Allow non-admin participants to use the text chat. -`user_data` _map_ - Arbitrary json data associated with this room +- `name` _str_ The room name. +- `description` _str_ A description of the room. +- `roomSize` _str_ The number of non-admin participants allowed into the room from the lobby at any given time. +- `sceneId` _str_ The seven character id of the scene hosted on the server. +- `sceneUrl` _str_ A hosted asset to be used as the scene. Frequently used for specifying .glb files as scenes. +- `memberPermissions` _map_ A map of the permissions non-admin participants should have in the room. + - `spawnAndMoveMedia` _bool_ Allow non-admin participants to spawn and move media. + - `spawnCamera` _bool_ Allow non-admin participants to spawn in-game cameras. + - `spawnDrawing` _bool_ Allow non-admin participants to draw with a pen. + - `pinObjects` _bool_ Allow non-admin participants to pin media to the room. + - `spawnEmoji` _bool_ Allow non-admin participants to spawn emoji. + - `fly` _bool_ Allow non-admin participants to toggle fly mode. + - `voiceChat` _bool_ Allow non-admin participants to use the voice chat. + - `textChat` _bool_ Allow non-admin participants to use the text chat. +- `user_data` _map_ Arbitrary json data associated with this room. See [room_types.ex](../lib/ret_web/schema/room_types.ex) for full GraphQL Schema. From 2f63b9cde366e5dee258b0d927e7c7dc3f5155b1 Mon Sep 17 00:00:00 2001 From: Michael Morran <67967136+mikemorran@users.noreply.github.com> Date: Thu, 16 Feb 2023 10:58:57 -0600 Subject: [PATCH 3/5] Fixing markdown formatting --- guides/api.md | 30 +++++++++++++++--------------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/guides/api.md b/guides/api.md index d87b575f2..142e22c84 100644 --- a/guides/api.md +++ b/guides/api.md @@ -32,21 +32,21 @@ Scopes, actions, and token types are expected to expand over time. ## Write_Rooms The following parameters can be written to individual rooms on `createRoom` or `updateRoom`. -- `name` _str_ The room name. -- `description` _str_ A description of the room. -- `roomSize` _str_ The number of non-admin participants allowed into the room from the lobby at any given time. -- `sceneId` _str_ The seven character id of the scene hosted on the server. -- `sceneUrl` _str_ A hosted asset to be used as the scene. Frequently used for specifying .glb files as scenes. -- `memberPermissions` _map_ A map of the permissions non-admin participants should have in the room. - - `spawnAndMoveMedia` _bool_ Allow non-admin participants to spawn and move media. - - `spawnCamera` _bool_ Allow non-admin participants to spawn in-game cameras. - - `spawnDrawing` _bool_ Allow non-admin participants to draw with a pen. - - `pinObjects` _bool_ Allow non-admin participants to pin media to the room. - - `spawnEmoji` _bool_ Allow non-admin participants to spawn emoji. - - `fly` _bool_ Allow non-admin participants to toggle fly mode. - - `voiceChat` _bool_ Allow non-admin participants to use the voice chat. - - `textChat` _bool_ Allow non-admin participants to use the text chat. -- `user_data` _map_ Arbitrary json data associated with this room. +- `name` _**str**_ \| The room name. +- `description` _**str**_ \| A description of the room. +- `roomSize` _**str**_ \| The number of non-admin participants allowed into the room from the lobby at any given time. +- `sceneId` _**str**_ \| The seven character id of the scene hosted on the server. +- `sceneUrl` _**str**_ \| A hosted asset to be used as the scene. Frequently used for specifying .glb files as scenes. +- `memberPermissions` _**map**_ \| A map of the permissions non-admin participants should have in the room. + - `spawnAndMoveMedia` _**bool**_ \| Allow non-admin participants to spawn and move media. + - `spawnCamera` _**bool**_ \| Allow non-admin participants to spawn in-game cameras. + - `spawnDrawing` _**bool**_ \| Allow non-admin participants to draw with a pen. + - `pinObjects` _**bool**_ \| Allow non-admin participants to pin media to the room. + - `spawnEmoji` _**bool**_ \| Allow non-admin participants to spawn emoji. + - `fly` _**bool**_ \| Allow non-admin participants to toggle fly mode. + - `voiceChat` _**bool**_ \| Allow non-admin participants to use the voice chat. + - `textChat` _**bool**_ \| Allow non-admin participants to use the text chat. +- `user_data` _**map**_ \| Arbitrary json data associated with this room. See [room_types.ex](../lib/ret_web/schema/room_types.ex) for full GraphQL Schema. From 8a858fedd3c57753f36021a5c75118ada05e2574 Mon Sep 17 00:00:00 2001 From: Michael Morran <67967136+mikemorran@users.noreply.github.com> Date: Fri, 17 Feb 2023 11:37:02 -0600 Subject: [PATCH 4/5] Adding simplified sample workspace with instrospection --- ...raphiql-workspace-2023-02-17-11-24-40.json | 137 ++++++++++++++++++ 1 file changed, 137 insertions(+) create mode 100644 test/api/v2/graphiql-workspace-2023-02-17-11-24-40.json diff --git a/test/api/v2/graphiql-workspace-2023-02-17-11-24-40.json b/test/api/v2/graphiql-workspace-2023-02-17-11-24-40.json new file mode 100644 index 000000000..aa953d070 --- /dev/null +++ b/test/api/v2/graphiql-workspace-2023-02-17-11-24-40.json @@ -0,0 +1,137 @@ +{ + "key": "graphiql", + "lastId": 9, + "tabIds": [ + "tab2", + "tab3", + "tab5", + "tab8", + "tab9" + ], + "closedTabs": [], + "defaultUrl": "https://HOSTUPDATEME/api/v2_alpha/graphiql", + "defaultWebsocketUrl": "", + "defaultQuery": "", + "defaultVariables": "", + "defaultProxy": false, + "defaultHeaders": [ + { + "name": "authorization", + "value": "TOKENUPDATEME" + } + ], + "usedUrls": [], + "recentHeaders": [], + "maxTabHistory": 20, + "maxUrlHistory": 20, + "maxHistory": 20, + "savedQueries": [], + "activeId": "tab9", + "tabs": [ + { + "id": "tab2", + "name": "queries", + "websocketUrl": "", + "proxy": false, + "collapsed": false, + "maxHistory": 20, + "url": "https://HOSTUPDATEME/api/v2_alpha/graphiql", + "headers": [ + { + "name": "authorization", + "value": "TOKENUPDATEME" + } + ], + "history": [], + "graphiql:query": "query {\n myRooms(page: 1, pageSize: 3) {\n entries {\n name,\n description,\n id,\n memberPermissions{\n fly\n },\n creatorAssignmentToken,\n defaultEnvironmentGltfBundleUrl,\n scene {\n ... on Scene {\n name,\n id\n }\n ... on SceneListing{\n name,\n id\n }\n }\n }\n }\n \n favoriteRooms(page: 1, pageSize: 3) {\n entries {\n name,\n id,\n memberPermissions{\n fly\n }\n defaultEnvironmentGltfBundleUrl,\n scene {\n ... on Scene {\n name,\n id\n }\n ... on SceneListing{\n name,\n id\n }\n }\n }\n }\n \n publicRooms(page: 1, pageSize: 3) {\n entries {\n name,\n id,\n memberPermissions{\n fly\n }\n defaultEnvironmentGltfBundleUrl,\n scene {\n ... on Scene {\n name,\n id\n }\n ... on SceneListing{\n name,\n id\n }\n }\n }\n }\n}", + "graphiql:queries": "{\"queries\":[{\"query\":\"query {\\n myRooms(page: 2, pageSize: 5) {\\n entries {\\n name,\\n id,\\n memberPermissions{\\n fly\\n }\\n }\\n }\\n}\",\"variables\":\"\"},{\"query\":\"query {\\n publicRooms(page: 2, pageSize: 5) {\\n entries {\\n name,\\n id,\\n memberPermissions{\\n fly\\n }\\n }\\n }\\n}\"},{\"query\":\"query {\\n publicRooms(page: 1, pageSize: 5) {\\n entries {\\n name,\\n id,\\n memberPermissions{\\n fly\\n }\\n }\\n }\\n}\"},{\"query\":\"query {\\n myRooms(page: 1, pageSize: 3) {\\n entries {\\n name,\\n id,\\n memberPermissions{\\n fly\\n }\\n }\\n }\\n \\n favoriteRooms(page: 1, pageSize: 3) {\\n entries {\\n name,\\n id,\\n memberPermissions{\\n fly\\n }\\n }\\n }\\n \\n publicRooms(page: 1, pageSize: 3) {\\n entries {\\n name,\\n id,\\n memberPermissions{\\n fly\\n }\\n }\\n }\\n}\"},{\"query\":\"query {\\n myRooms(page: 1, pageSize: 3) {\\n entries {\\n name,\\n description,\\n id,\\n memberPermissions{\\n fly\\n }\\n }\\n }\\n \\n favoriteRooms(page: 1, pageSize: 3) {\\n entries {\\n name,\\n id,\\n memberPermissions{\\n fly\\n }\\n }\\n }\\n \\n publicRooms(page: 1, pageSize: 3) {\\n entries {\\n name,\\n id,\\n memberPermissions{\\n fly\\n }\\n }\\n }\\n}\"},{\"query\":\"query {\\n myRooms(page: 1, pageSize: 3) {\\n entries {\\n name,\\n description,\\n id,\\n memberPermissions{\\n fly\\n },\\n scene {\\n ...on Scene {\\n name,\\n id\\n }\\n }\\n }\\n }\\n \\n favoriteRooms(page: 1, pageSize: 3) {\\n entries {\\n name,\\n id,\\n memberPermissions{\\n fly\\n }\\n }\\n }\\n \\n publicRooms(page: 1, pageSize: 3) {\\n entries {\\n name,\\n id,\\n memberPermissions{\\n fly\\n }\\n }\\n }\\n}\"},{\"query\":\"query {\\n myRooms(page: 1, pageSize: 3) {\\n entries {\\n name,\\n description,\\n id,\\n memberPermissions{\\n fly\\n },\\n defaultEnvironmentGltfBundleUrl,\\n scene {\\n ... on Scene {\\n name,\\n id\\n }\\n ... on SceneListing{\\n name,\\n id\\n }\\n }\\n }\\n }\\n \\n favoriteRooms(page: 1, pageSize: 3) {\\n entries {\\n name,\\n id,\\n memberPermissions{\\n fly\\n }\\n defaultEnvironmentGltfBundleUrl,\\n scene {\\n ... on Scene {\\n name,\\n id\\n }\\n ... on SceneListing{\\n name,\\n id\\n }\\n }\\n }\\n }\\n \\n publicRooms(page: 1, pageSize: 3) {\\n entries {\\n name,\\n id,\\n memberPermissions{\\n fly\\n }\\n defaultEnvironmentGltfBundleUrl,\\n scene {\\n ... on Scene {\\n name,\\n id\\n }\\n ... on SceneListing{\\n name,\\n id\\n }\\n }\\n }\\n }\\n}\"},{\"query\":\"query {\\n myRooms(page: 1, pageSize: 3) {\\n entries {\\n name,\\n description,\\n id,\\n memberPermissions{\\n fly\\n },\\n creatorAssignmentToken,\\n defaultEnvironmentGltfBundleUrl,\\n scene {\\n ... on Scene {\\n name,\\n id\\n }\\n ... on SceneListing{\\n name,\\n id\\n }\\n }\\n }\\n }\\n \\n favoriteRooms(page: 1, pageSize: 3) {\\n entries {\\n name,\\n id,\\n memberPermissions{\\n fly\\n }\\n defaultEnvironmentGltfBundleUrl,\\n scene {\\n ... on Scene {\\n name,\\n id\\n }\\n ... on SceneListing{\\n name,\\n id\\n }\\n }\\n }\\n }\\n \\n publicRooms(page: 1, pageSize: 3) {\\n entries {\\n name,\\n id,\\n memberPermissions{\\n fly\\n }\\n defaultEnvironmentGltfBundleUrl,\\n scene {\\n ... on Scene {\\n name,\\n id\\n }\\n ... on SceneListing{\\n name,\\n id\\n }\\n }\\n }\\n }\\n}\"}]}", + "graphiql:docExplorerWidth": 350, + "graphiql:variableEditorHeight": 200, + "graphiql:editorFlex": 1 + }, + { + "id": "tab3", + "name": "createRoom", + "websocketUrl": "", + "proxy": false, + "headers": [ + { + "name": "authorization", + "value": "TOKENUPDATEME" + } + ], + "url": "https://HOSTUPDATEME/api/v2_alpha/graphiql", + "collapsed": false, + "maxHistory": 20, + "history": [], + "graphiql:query": "mutation {\n createRoom(description: \"A room with a view\", allowPromotion:false) {\n id,\n name,\n allowPromotion,\n memberPermissions{\n fly\n },\n embedToken,\n creatorAssignmentToken,\n roomSize\n }\n}", + "graphiql:queries": "{\"queries\":[{\"query\":\"mutation {\\n createRoom(description: \\\"A room with a view\\\") {\\n id\\n }\\n}\",\"variables\":\"\"},{\"query\":\"mutation {\\n createRoom(description: \\\"A room with a view\\\") {\\n id,\\n name\\n }\\n}\",\"variables\":\"\"},{\"query\":\"mutation {\\n createRoom(description: \\\"A room with a view\\\") {\\n id,\\n name,\\n allowPromotion,\\n memberPermissions{\\n fly\\n }\\n }\\n}\"},{\"query\":\"mutation {\\n createRoom(description: \\\"A room with a view\\\") {\\n id,\\n name,\\n allowPromotion,\\n memberPermissions{\\n fly\\n },\\n embedToken\\n }\\n}\"},{\"query\":\"mutation {\\n createRoom(description: \\\"A room with a view\\\", allowPromotion:false) {\\n id,\\n name,\\n allowPromotion,\\n memberPermissions{\\n fly\\n },\\n embedToken\\n }\\n}\"},{\"query\":\"mutation {\\n createRoom(description: \\\"A room with a view\\\", allowPromotion:false) {\\n id,\\n name,\\n allowPromotion,\\n memberPermissions{\\n fly\\n },\\n embedToken,\\n creatorAssignmentToken\\n }\\n}\"},{\"query\":\"mutation {\\n createRoom(description: \\\"A room with a view\\\", allowPromotion:false) {\\n id,\\n name,\\n allowPromotion,\\n memberPermissions{\\n fly\\n },\\n embedToken,\\n creatorAssignmentToken,\\n roomSize\\n }\\n}\"}]}", + "graphiql:variableEditorHeight": 200, + "graphiql:editorFlex": 1, + "graphiql:docExplorerWidth": 350 + }, + { + "id": "tab5", + "name": "updateRoom", + "websocketUrl": "", + "proxy": false, + "headers": [ + { + "name": "authorization", + "value": "TOKENUPDATEME" + } + ], + "url": "https://HOSTUPDATEME/api/v2_alpha/graphiql", + "collapsed": false, + "maxHistory": 20, + "history": [], + "graphiql:query": "mutation {\n updateRoom(id: \"7VkWtfB\", description: \"A room with an APP view\") {\n description,\n id,\n name,\n allowPromotion,\n memberPermissions{\n fly\n },\n embedToken\n }\n}", + "graphiql:variableEditorHeight": 200, + "graphiql:editorFlex": 1, + "graphiql:queries": "{\"queries\":[{\"query\":\"mutation {\\n createRoom(description: \\\"A room with a view\\\") {\\n id,\\n name,\\n allowPromotion,\\n memberPermissions{\\n fly\\n },\\n embedToken\\n }\\n}\",\"variables\":\"\"},{\"query\":\"mutation {\\n updateRoom(id: \\\"EzqydXp\\\", description: \\\"Aasddas view\\\") {\\n description,\\n id,\\n name,\\n allowPromotion,\\n memberPermissions{\\n fly\\n },\\n embedToken\\n }\\n}\",\"variables\":\"\"},{\"query\":\"mutation {\\n updateRoom(id: \\\"maJCnRD\\\", description: \\\"Aasddas view\\\") {\\n description,\\n id,\\n name,\\n allowPromotion,\\n memberPermissions{\\n fly\\n },\\n embedToken\\n }\\n}\",\"variables\":\"\"},{\"query\":\"mutation {\\n updateRoom(id: \\\"maJCnRD\\\", description: \\\"fffff view\\\") {\\n description,\\n id,\\n name,\\n allowPromotion,\\n memberPermissions{\\n fly\\n },\\n embedToken\\n }\\n}\",\"variables\":\"\"},{\"query\":\"mutation {\\n updateRoom(id: \\\"maJCnRD\\\", description: \\\"fggggg view\\\") {\\n description,\\n id,\\n name,\\n allowPromotion,\\n memberPermissions{\\n fly\\n },\\n embedToken\\n }\\n}\",\"variables\":\"\"},{\"query\":\"mutation {\\n updateRoom(id: \\\"maJCnRD\\\", description: \\\"A room with an APP view\\\") {\\n description,\\n id,\\n name,\\n allowPromotion,\\n memberPermissions{\\n fly\\n },\\n embedToken\\n }\\n}\"},{\"query\":\"mutation {\\n updateRoom(id: \\\"7VkWtfB\\\", description: \\\"A room with an APP view\\\") {\\n description,\\n id,\\n name,\\n allowPromotion,\\n memberPermissions{\\n fly\\n },\\n embedToken\\n }\\n}\"}]}", + "graphiql:docExplorerWidth": 350 + }, + { + "id": "tab8", + "name": "introspection more", + "url": "https://HOSTUPDATEME/api/v2_alpha/graphiql", + "websocketUrl": "", + "proxy": false, + "headers": [ + { + "name": "authorization", + "value": "TOKENUPDATEME" + } + ], + "collapsed": false, + "maxHistory": 20, + "history": [], + "graphiql:query": "query {\n __schema {\n types {\n name\n kind\n fields {\n name\n description\n type {\n name\n }\n }\n }\n }\n}", + "graphiql:variables": "", + "graphiql:editorFlex": 1, + "graphiql:variableEditorHeight": 200, + "graphiql:docExplorerWidth": 350 + }, + { + "id": "tab9", + "name": "introspection less", + "url": "https://HOSTUPDATEME/api/v2_alpha/graphiql", + "websocketUrl": "", + "proxy": false, + "headers": [ + { + "name": "authorization", + "value": "TOKENUPDATEME" + } + ], + "collapsed": false, + "maxHistory": 20, + "history": [], + "graphiql:query": "query {\n __schema {\n types {\n name\n description\n } \n }\n}", + "graphiql:variables": "", + "graphiql:editorFlex": 1, + "graphiql:variableEditorHeight": 200, + "graphiql:docExplorerWidth": 350 + } + ] +} From 595fdd26b245b279e329a66b3af0ac06790b6014 Mon Sep 17 00:00:00 2001 From: Michael Morran <67967136+mikemorran@users.noreply.github.com> Date: Fri, 17 Feb 2023 11:51:18 -0600 Subject: [PATCH 5/5] Adding Introspection and Simplified Workspace I decided to remove the list of writable parameters in favor of John's suggestion to include the introspection tools. I have also linked a new version of the workspace which is simplified to 5 tabs, including introspection queries. QUESTION @ john & bryan: Why did the older example workspace include tabs for both app and user tokens? This was confusing to me, but I don't want to omit any important materials, especially if there is an important distinction to be made in this example space. --- guides/api.md | 29 +++++++---------------------- 1 file changed, 7 insertions(+), 22 deletions(-) diff --git a/guides/api.md b/guides/api.md index 142e22c84..92422d80f 100644 --- a/guides/api.md +++ b/guides/api.md @@ -1,7 +1,7 @@ # Hubs Server API Reticulum includes a [GraphQL](https://graphql.org/) API that grants programmatic access to server resources. -Note: This API is currently in alpha testing and will likely experience frequent updates. +Note: This API is not yet stable, and may undergo breaking changes in future updates. ## Accessing the API Hubs Cloud administrators can enable or disable the API by toggling `App Settings > Features > Public API Access` in the admin panel. @@ -30,33 +30,18 @@ Each API Access Token specifies its `scopes`. Scopes allow a token to be used to Scopes, actions, and token types are expected to expand over time. -## Write_Rooms -The following parameters can be written to individual rooms on `createRoom` or `updateRoom`. -- `name` _**str**_ \| The room name. -- `description` _**str**_ \| A description of the room. -- `roomSize` _**str**_ \| The number of non-admin participants allowed into the room from the lobby at any given time. -- `sceneId` _**str**_ \| The seven character id of the scene hosted on the server. -- `sceneUrl` _**str**_ \| A hosted asset to be used as the scene. Frequently used for specifying .glb files as scenes. -- `memberPermissions` _**map**_ \| A map of the permissions non-admin participants should have in the room. - - `spawnAndMoveMedia` _**bool**_ \| Allow non-admin participants to spawn and move media. - - `spawnCamera` _**bool**_ \| Allow non-admin participants to spawn in-game cameras. - - `spawnDrawing` _**bool**_ \| Allow non-admin participants to draw with a pen. - - `pinObjects` _**bool**_ \| Allow non-admin participants to pin media to the room. - - `spawnEmoji` _**bool**_ \| Allow non-admin participants to spawn emoji. - - `fly` _**bool**_ \| Allow non-admin participants to toggle fly mode. - - `voiceChat` _**bool**_ \| Allow non-admin participants to use the voice chat. - - `textChat` _**bool**_ \| Allow non-admin participants to use the text chat. -- `user_data` _**map**_ \| Arbitrary json data associated with this room. - -See [room_types.ex](../lib/ret_web/schema/room_types.ex) for full GraphQL Schema. - ## Examples Reticulum ships with [GraphiQL](https://github.com/graphql/graphiql/tree/main/packages/graphiql#graphiql), a graphical, interactive, in-browser GraphQL IDE that makes it easier to test and learn the API. It can be accessed by navigating to `/api/v2_alpha/graphiql`. -[This example workspace](../test/api/v2/graphiql-workspace-2020-12-07-15-26-56.json) demonstrates several queries and can be loaded into the GraphiQL interface. You will have to supply your own API access token(s). +[This example workspace](../test/api/v2/graphiql-workspace-2023-02-17-11-24-40.json) demonstrates several queries and can be loaded into the GraphiQL interface. In the workspace, you will have to supply your own API access token(s) (see `TOKENUPDATEME` in file) and the host name of your deployment (see `HOSTUPDATEME` in file). Requests can also be sent by - an `HTTP` client library, - a command line tool like `curl`, - a GraphQL-specific client library, or - any other tool that speaks `HTTP`. + +## What Can You Read and Write +GraphQL includes [handy introspection tools](https://graphql.org/learn/introspection/) which you can accessed through the IDE. The sample workspace above includes examples of introspection queries to learn about the parameters which can be manipulated through the API. + +See [room_types.ex](../lib/ret_web/schema/room_types.ex) for full GraphQL Schema.