Overview
Concepts
Studio is the CMS where users manage all of their screens and the content on them.
GraphQL is the language standard used to interact with the Studio API.
NOTE: In general we will use queries and calls and requests interchangeably through this document to mean "an HTTP request against the GraphQL API". The official GraphQL docs refer to this as an operation.
Why GraphQL
GraphQL is a an expressive language to describe data.
It allows you to very quickly fetch exactly the data that you want, rather than the data that the API creator prescribes for you. It also allows you to interactively explore the entire API at your fingertips. GraphQL also features a strong type system that allows typesafe queries and autocompletion during development.
Using the Studio GraphQL API, you can quickly and easily build deep interactions with the same powerful tools that the Studio Frontend team uses to build our screen management CMS.
Differences from REST APIs
Only one endpoint
If you're familiar with REST APIs, you're likely used to fetching data from multiple endpoints, and then combining that data together in the client. However, in GraphQL, there is typically only one endpoint which can be used to fetch or mutate any data.
No versioning
There is not yet a fully implemented specification for versioning the API schema. In general, REST APIs must version the entire schema after any breaking change, using different URL endpoints such as /v1, /v2, etc.
However, in GraphQL you will generally always get the latest available fields on any query. Because the schema is continually evolving, fields that existed yesterday, may not exist today, and new fields may be added at any time.
Fetch only what you need
Unlike in REST APIs where you will need to make multiple queries in order to get the data you need to construct further queries, in GraphQL you can generally fetch everything in one query. That's because the schema exposes not just fields that you may want to query such as the name of a resource, but also relations, which can be nested arbitrarily deeply.
For instance you may want to fetch all Books belonging to an Author, and also get all the Publishers who have published those books in different Countries. In a REST API this would be multiple unwieldy queries, but in GraphQL, it's just one.
Interactive exploration
Because the GraphQL schema is already defined, it's much easier to experiment and play with the API than reading long REST API docs. The closest equivalent would be Swagger/OpenAPI docs.
Using a a GraphQL browser to interactively explore the API is the best possible way to see what you can make with the Studio API.
New language
Making GraphQL queries requires learning the GraphQL language, which superfically looks like JSON. The official GraphQL docs do an excellent job of guiding you through forming queries and mutations.
While the GraphQL spec is technically transport-agnostic, the ScreenCloud Studio API only accepts calls over HTTP.
Tools
You can use any text editor or IDE to write GraphQL queries, but we recommend any of the following to use for testing out your queries before using them in production. Consider these like a REPL for making requests.
When designing your implementation, you will also need a GraphQL client library to make requests. Client libraries are available for many programming languages.
Getting Support
Our All-Star Support team is always available to answer requests.