Programmatic Space Management

Project Complexity: ★★☆☆☆

In your application, you may need to create and delete Spaces as they're needed rather than creating them ahead of time using the High Fidelity Audio API Developer Console. For instance, when a new user visits your website, you may want to give them the opportunity to create a brand new Space that is dedicated to their particular group of friends.

In addition to creating spaces manually with the Developer Console, you can programmatically manage Spaces using the Administrative High Fidelity Spatial Audio REST API.

In order to make a call to the administrative REST API, you will need to authenticate your request using a special JWT that has an admin boolean set to true and contains the App ID for which you want to generate the space.

For example, if you wanted to generate an Administrative JWT, you might start with a set of keys and values such as these:

{
    "user_id": "app-test-admin",
    "app_id": "aaaaaaaa-1111-bbbb-2222-cccccccccccc",
    "admin": true
}

For more information about generating and using JWTs to authenticate your High Fidelity requests, visit the "Get a JWT" guide.

In this guide, you will learn how to:

1. Sign up to use the High Fidelity Spatial Audio API
2. Create a Space using the High Fidelity Spatial Audio REST API
3. Delete a Space using the REST API
4. Change Space Settings using the REST API

Sign Up to use the High Fidelity Spatial Audio API

If you already have a High Fidelity Developer Account, you can jump straight to the next step.

Before your app can make use of the Spatial Audio API, you'll need a High Fidelity Developer Account. Sign up for an account or log in here.

Create a Space using the High Fidelity Spatial Audio REST API

To create a Space, make a GET or POST HTTP request to the api/v1/spaces/create?token=$TOKEN endpoint, replacing $TOKEN with an Administrative JWT.

Here's an example of how to use this endpoint with cURL:

curl 'https://api.highfidelity.com/api/v1/spaces/create?token=$TOKEN'

If you want to set a name for the new Space at the same time, provide a name query parameter with your request, as in this cURL example:

curl 'https://api.highfidelity.com/api/v1/spaces/create?token=$TOKEN&name=MyTestSpace'

Requests to the api/v1/spaces/create endpoint will respond with JSON data containing the App ID embedded in your JWT and the ID of the newly-created Space. For example, a response may look like this:

{
  "app-id":"ddf3d020-0000-0000-0000-502e4d0b40ed",
  "space-id":"64719f3b-0000-0000-0000-9779ed7a92a9"
}

You can use the space-id returned in the response to direct your users to the new Space.

You can verify that your Space was created by looking at the High Fidelity Audio API Developer Console.

Delete a Space using the High Fidelity Spatial Audio REST API

To delete a Space, make a DELETE HTTP request to the api/v1/spaces/$SPACE_UUID?token=$TOKEN endpoint, replacing $SPACE_UUID with the ID of the Space to delete, and replacing $TOKEN with an Administrative JWT.

Here's an example of how to use this endpoint with cURL:

curl -X "DELETE" 'https://api.highfidelity.com/api/v1/spaces/$SPACE_UUID?token=$TOKEN'

DELETE requests to the api/v1/spaces/ endpoint will respond with JSON data containing the App ID embedded in your JWT and the ID of the deleted Space. For example, a response may look like this:

{
  "app-id":"ddf3d020-0000-0000-0000-502e4d0b40ed",
  "space-id":"64719f3b-0000-0000-0000-9779ed7a92a9"
}

Once a Space is deleted, nobody will be able to access that Space, even if its Space ID is embedded within a JWT.

You can verify that your Space was deleted by looking at the High Fidelity Audio API Developer Console.

Change a Space's Settings using the High Fidelity Spatial Audio REST API

You can change Space Settings using a GET or POST HTTP request to the api/v1/spaces/$SPACE_ID/settings/?token=$TOKEN endpoint, replacing $SPACE_UUID with the ID of the Space to delete, and replacing $TOKEN with an Administrative JWT.

All Available Space Settings

Readable and Writable Space Settings include:

• name - The Space Name
• new-connections-allowed - true if new client connections are allowed to the Space; false otherwise.
• ignore-token-signing - If true, client JWTs will not need to be signed with your App Secret to connect.

Read-only Space Settings include:

• app-id
• space-id

Setting Space Settings with a GET Request

Here's an example of how to change multiple settings simultaneously with a GET request using cURL:

curl 'https://api.highfidelity.com/api/v1/spaces/$SPACE_ID/settings?token=$ADMIN_TOKEN&new-connections-allowed=false&name=foobar'

Setting Space Settings with a POST Request

Here's an example of how to change multiple settings simultaneously with a POST request using cURL:

curl -d 'name=blop&ignore-token-signing=true' 'https://api.highfidelity.com/api/v1/spaces/$SPACE_ID/settings?token=$ADMIN_TOKEN'

Getting Space Settings with a GET Request

Here's an example of how to read all Space Settings simultaneously with a GET request using cURL:

curl 'https://api.highfidelity.com/api/v1/spaces/$SPACE_ID/settings?token=$ADMIN_TOKEN'

Here's an example of how to read the name Space Setting with a GET request using cURL:

curl 'https://api.highfidelity.com/api/v1/spaces/$SPACE_ID/settings/name/?token=$ADMIN_TOKEN'

Here's an example of how to read the new-connections-allowed Space Setting with a GET request using cURL:

curl 'https://api.highfidelity.com/api/v1/spaces/$SPACE_ID/settings/new-connections-allowed/?token=$ADMIN_TOKEN'

Settings Endpoint Response

Requests to the api/v1/spaces/$SPACE_ID/settings endpoint will respond with JSON data containing the Space's Settings. For example, a response may look like this:

{
    "app-id":"ddf3d020-0000-0000-0000-502e4d0b40ed",
    "ignore-token-signing":true,
    "name":"foobar",
    "new-connections-allowed":false,
    "space-id":"64719f3b-0000-0000-0000-9779ed7a92a9"
}
                    

Conclusion

In this guide, you learned about how to programmatically manage Spaces within your High Fidelity Spatial Audio Application using the Administrative REST API.

For detailed technical information about the High Fidelity Spatial Audio Client API, visit the API documentation.

If you have any questions or comments, please reach out to support@highfidelity.com.