OS1 Concepts
Working with GraphQL
11min
overview graphql is a powerful query language for apis and provides a more efficient and flexible alternative to traditional rest api graphql allows developers to request the data they need, leading to more efficient and precise data retrieval this guide introduces graphql’s basic concepts, including terminology, structuring queries, and using a graphql explorer to interact with its apis graphql schemas graphql schemas are currently available for the following services graphql dispatch queries docid\ p2gjb ejnnrkti2vxwfiq graphql order queries docid\ nd5f7ksjjita1dqesnjlj graphql workflow queries docid 1vkoh9wtinvnywuoqpq2x graphql container queries docid 535b3tw fuqymma0aacba terminology before diving into writing queries, it’s important to understand some fundamental graphql concepts schema a schema defines the shape of your data it serves as a contract between the client and server, specifying the data structure and relationships that can be queried or modified fields fields are the properties of an object that you can query for example, in a query requesting user information, the fields might include name , age, and address` fields can also be nested, allowing you to request data on related objects within a single query arguments arguments allow you to pass variables to fields, enabling you to request specific data based on your requirements for example, you might request a specific user by providing a user id as an argument scalars scalar types represent the basic, concrete data types in a graphql schema, such as string , int , and boolean connections connections enable you to paginate and filter related objects by querying a graphql api connections are particularly useful when dealing with large sets of related data using a graphql explorer a graphql explorer is an interactive tool that helps you build and test graphql queries it provides features like auto completion, syntax highlighting, and real time error checking to make the process of writing and executing queries more efficient there are several graphql explorers available, such as graphiql, graphql playground, and apollo studio credentials before using the graphql explorer, you’ll need your tenant id and an access token tenant id follow the getting started using platform credentials guide to get your tenant id access token call the client credentials grant token endpoint to retrieve your access token follow the steps below to build and test queries in a graphql explorer open your preferred graphql explorer use {tenant} base/api/v2/core/api/v1/graphql/grapqhl endpoint for queries start writing your queries in the editor the example query below retrieves information about a specific dispatch , using the provided tenant and dispatch id to obtain the tenant and dispatchid arguments, we used the following api calls tenant get https //{base url}/core/api/v2/participants/tenants dispatchid post https //{base url}/core/api/v1/dispatch service/dispatches query query { dispatch(tenant "os1devs", dispatchid "dispatch 7abd9d35 8d2b 43c3 bf15 22fc3a9febe8") { createdat createdby customdata } } in this query, dispatch is the root of the query field that accepts tenant and dispatchid as arguments we also included the createdat , createdby , and customdata fields to be returned for the dispatch object result { "data" { "dispatch" { "id" "dispatch\ a0ab6199 14d6 4973 a91e 26618ab9e52b", "createdat" 1681878835466, "createdby" { "id" "id", "name" "name", "appid" "app 1d6ebc25 32df 4dfc b93b 4af5750dff37" } } } }