The Gem Bidirectional API allows users to Get, Update, or Delete various elements of their Gem project without having to interface with the Gem editor directly. Teams can do this by setting up their own solutions for this, but the contents may also be added via the "Swagger API" user interface, which can be accessed at https://games-api.celtx.com/docs/api/#/ while logged into Gem.
Introduction to the Swagger UI
The Swagger UI will provide you with a live directory of all the possible endpoints that you will be able to utilize, as well as example syntax for each.
Before attempting to use this interface, ensure that you are logged in to your Gem account at Script Writing Software for Storytellers.
You will need your project ID to utilize most endpoints. You can find this by utilizing the GET /api/project endpoint, which is the first one in the interface list.
The bottom of this page includes a list of recurring data models used on this API page.
When a request is made with a parameterId, that particular parameter such as a projectId will become the default value for every parameterId field when the page is refreshed. These defaults are cleared when all instances/tabs of this page are closed. This may not always work perfectly under some circumstances.
Known Limitations
Please be aware of the following limitations:
- New Projects: Projects must be loaded using the app editor and have some changes saved successfully before being usable. This will be addressed at a later date.
- Mass Transactions: Excessive and repeated calls made against a single element or component in rapid succession are known to compromise data integrity. Please use caution.
Using the Swagger UI
As you scroll down the page, you'll see a number of categories, which can be expanded; doing so will display the endpoints for each category.
Most endpoints will require some sort of defined parameters, with the exception of one - the 'Get Projects' endpoint, which will fetch a list of all the projects in the Gem account the users is concurrently logged into, as well as their IDs. These IDs will be used as parameters for all other endpoints.
Please note, however, most IDs can be retrieved from the Reports document in the project.
Calling the Project List
To view the project list, do the following:
Click "Try it out" to enable user interactions
Click "Execute," as no parameters are required for this endpoint other than being logged in to your Gem account.
The returned results will appear in the response body below. Make note of the ID(s) you want, as all other endpoints will require a project ID as a parameter input.
Parameters
As mentioned above, project IDs are used as parameters in other endpoints, and can be used to retrieve other types of IDs, which may, in turn, be used as parameters themselves. These are the types of parameters required across various endpoints:
- projectId
- episodeId
- sceneId
- modeId
- laneId
- catalogId
- catalogType
- conditionId
- variableId
- subdocumentId
- nodeId
- edgeId
- scriptId
- breakdownId
- elementId
Please note:
- subdocumentId refers to the associated 'laneId,'
- nodeId refers to the sequence nodes on the storymap in the Gem editor
- edgeId refers to the connection lines linking between nodes
- elementId refers to each line in the script
- For example: a line of gameplay, dialogue, a character element, etc
To use a parameter, for example, users may input the project ID to look up a list of all the Lane IDs used in the project. Just expand that endpoint, click "Try it out" to enable, input the project ID, and execute the function.
Updating Data
Updating Data takes defined parameters, as well request body text, and transmits the result to your Gem project, and updates the editor in real time. Let's update some Lane information:
As pictured in the image above, the PUT request has a Request Body. Users will need to replace the "lane.id" with the properly formatted ID for the lane they wish to update, as well as input the Lane name and description they wish to push to the project. Execute to push the change.
The response body will then once again retrieve the content to verify the change has been applied