Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update API.md with correction and new info #676

Open
wants to merge 5 commits into
base: master
Choose a base branch
from
Open

Update API.md with correction and new info #676

Changes from 3 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
b2317a0
Update API.md with correction and new info
mikemorran Feb 16, 2023
a35844c
Update api.md
mikemorran Feb 16, 2023
2f63b9c
Fixing markdown formatting
mikemorran Feb 16, 2023
8a858fe
Adding simplified sample workspace with instrospection
mikemorran Feb 17, 2023
595fdd2
Adding Introspection and Simplified Workspace
mikemorran Feb 17, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 24 additions & 2 deletions guides/api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I might just say, "This API is not yet stable, and may undergo breaking changes in future updates."

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed!


## Accessing the API
Hubs Cloud administrators can enable or disable the API by toggling `App Settings > Features > Public API Access` in the admin panel.
Expand All @@ -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: <your API token>`.

### API Access Token Types
### API Access Token Generation and Types
API Token can be generated and revoked though an interface located at `<your_hubs_cloud_host>/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
Expand All @@ -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.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you for writing this.

I am torn on whether to include it, because GraphQL has built-in __schema field that allows users to learn about a query: https://graphql.org/learn/introspection/

The built-in method has no risk of being outdated or wrong as we change things, whereas having this data duplicated here means that we risk forgetting to update it, or making a mistake.

I would not want to recreate the documentation that the graphql team already worked hard to write -- Perhaps we should link the graphql documentation and include some introspection queries in our sample workspace file.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I did not know about this and agree we should utilize this tool which will prevent us from having to constantly update. I will review the docs tomorrow and put together a bit more of a step-by-step of how to quickly see what is available.

## 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 `<your_hubs_cloud_host>/api/v2_alpha/graphiql`.

Expand Down