Skip to content

GraphQL Basics

GraphQL: the basics

  • The GraphQL query language is comparable with the JSON format with some extensions
  • It follows the “you get what you requested” approach. You have to define every property you want to get back as a result, however, it is guaranteed that you get back the exact data structure as requested
  • Use the Query statement to read data (comparable with GET in REST) and the Mutation statement to create or update data (comparable with POST and PUT in REST)
  • For all Mutations, the GraphQL API behaves like a “state machine”. In other words: the API will apply all identified differences between the database and your request to match the “state” you sent in. Two examples to clarify:
    • The Usercentrics database stores your settings using 3 consentTemplates A,B and C. Sending in a Mutation request which only contains the firstUserInteraction in its argument will not change the consentTemplates data, as the Mutation does not contain the consentTemplates field. Alternatively, you can think about Mutations as "partial update" operations, as they will apply changes only to what was provided in the input and won't change the rest of the record.
    • Especially important when working with list/arrays: Given the same example, but this time the Mutation contains a consentTemplates field with one entry Consent D. To match the “state” in the Mutation the API will delete the references to Consents A,B,C and will add Consent D to your setting. Having the “states” principle in mind is important here, because if you would’ve liked to keep the other Consent references you have to send the complete state (containing Consent A,B,C,D) to the API

For a complete introduction and a list of GraphQL clients compatible with your programming language, please refer to https://graphql.org .