circuit-desktop-1500x770

Introducing the Platform SDK and the deployment and snapshot APIs

21 August 2018

Back in June, we told you about our plans to enable user-created tools, workflows and services with an API-first approach for SpatialOS. Today we’re delighted to announce the availability of the first iteration of the Platform SDK, with the first two APIs for interfacing with the deployment service and snapshot service respectively. In this post, we show how the new APIs enable certain workflows, we provide links to full tutorials and code examples for those workflows, and we explain how you can get hold of the Platform SDK today.

The new APIs

The new APIs are for interfacing with the deployment and snapshot services. The deployment service lets you list, create, update and stop deployments, and the snapshot service lets you list, take, download and upload snapshots.

Previously it was only possible to access these services through the spatial CLI, which made it difficult to automate workflows. The new APIs provide a consistent interface to interact with both local and cloud deployments, making it easy to produce workflows compatible with both environments.

Example workflows

The intention of the Platform SDK is to enable users to create their own tools, workflows and services. The possible functionality will increase as we add APIs, but below are a couple of examples made possible with just the new deployment and snapshot APIs. For each example we have full tutorials and code examples, accessible through our docs. Please check them out and let us know what you think in our forums.

Game maintenance

Games in production may require a maintenance window, for example, if you want to add features or release upgrades. This example workflow automates the maintenance process while ensuring there is no loss of game progress. It achieves this by replicating the current game state as part of the deployment process.

Check out ‘maintenance’ in the docs.

Replicate local state to cloud

Throughout the production process, you may want to reproduce the local state of your deployment in the cloud (or vice versa, if you want to reproduce a cloud deployment locally). For example, after debugging locally you may want to test your scenario is reproducible in the cloud environment.

Check out ‘replicate local state to cloud’ in the docs. 

What’s next?

In the next two to three months, we expect to deliver alpha APIs for player management services and service account services; we will announce when these are available.

The API for the player management service will initially introduce a new authentication flow, allowing you to generate player identity tokens which you can combine with the deployment and snapshot services to build matchmaking.

The API for service account services will let you automatically generate and maintain service accounts, with defined access control privileges to run your maintenance scripts or continuous integration jobs.

Get started now – download the Platform SDK

The new APIs are available through the Platform SDK, which is initially available in C#. You can download it using the spatial CLI, with the following retrieval command:

spatial package retrieve platform_sdk csharp 13.2.0 <file_name>.zip

Alternatively, you can access it through NuGet, here.

Please note: to ensure your local deployments will accept API calls, you need to update to the latest version of spatial (‘20180815’ onwards) by running ‘spatialupdate’. Then, you need to enable local deployment access using ‘spatial service start’. You can find more information about doing this here.

We are considering this an alpha release, because we want to hear your feedback on the functionality and interface. Please provide feedback and discuss your experience in our forums and Discord!