GraphQL & SDL

Anil Talla
Aug 26, 2018 · 4 min read

REST has been an industry standard for API design. It is simple, well-documented which makes it easy to adopt.

REST problem:

One of the basic problems with conventional REST is the failure of the client to demand a personalized data set. In addition to that, running and controlling multiple endpoints is another difficulty as clients are mostly needed to request data from diversified endpoints.

GraphQL?

  • GraphQL is the new way of developing APIs
  • GraphQL is a query language for your API
  • GraphQL is a runtime for fulfilling queries with your existing data. GraphQL provides a complete and understandable description of the data in your API, gives clients the power to ask for exactly what they need and nothing more, makes it easier to evolve APIs over time, and enables powerful developer tools
  • GraphQL execution accepts request as a “GraphQL document” and provides JSON response.
  • Facebook provides a Specification to build GraphQL APIs
  • GraphQL schema is Domain specific

GraphQL similarities with REST

While talking about the similarities, both REST and GraphQL are used for building API’s. Plus, both of them can be managed over HTTP

GraphQL vs REST

GraphQL is not

  • A Graph database query language
  • A client-side state management solution
  • A solution for binary streams (Video streaming, File transfer etc)
  • Microsoft Graph API
  • Limited to specific database(s)
  • Limited to HTTP (It works with plain TCP or web sockets too)

GraphQL solves the following challenges with Modern APIs

  • Efficiency: Solves over-fetching & under-fetching problem. Over-fetching occurs when response contained too much data, GraphQL provides a mechanism for Client to specify the data what it requires. Under-fetching occurs when response did not contain enough data and API consumers are forced to call multiple APIs to retrieve data.
  • Predictability: Solves predictability by enforcing “Type safety” at the schema level & enabling DDD (Domain driven design)
  • Versioning: GraphQL promotes “No Versioning” by providing way to deprecate fields.
  • Tooling & Documentation : GraphQL introspection tools like GraphiQL, GraphQL playground etc provide good tooling for API consumers.

What are available GraphQL operations?

  • Query: Read
  • Mutation: Write
  • Subscription: Observe event

GraphQL Queries: Queries are data requests made by the client to the server. GraphQL only discloses single endpoint, enabling the client to determine what information it actually requires from a predefined framework

GraphQL Mutations: Mutations are used to create, update or delete data. The structure is almost similar to queries except for the fact that you need to include the word ‘mutation’ in the beginning.

GraphQL Subscriptions: Subscriptions can be used to set up and retain real-time link to the server. This allows you to get instant information regarding relevant events. Mostly, a client needs to subscribe to the particular event in order to get the corresponding data

GraphQL SDL (Schema definition language)

  • GraphQL has its own language to write GraphQL Schemas
  • SDL is simple and intuitive to use while being extremely powerful and expressive
  • A GraphQL Schema Definition is the most concise way to specify a GraphQL schema. The syntax is well-defined and are part of the official GraphQL specification

GraphQL type

A type has a name and can implement one or more interfaces

GraphQL field

A field has a name and a type

GraphQL scalar types

The GraphQL spec defines some built-in scalar values but more can be defined by a concrete implementation.

The built in scalar types are

  • Int
  • Float
  • String
  • Boolean
  • ID

GraphQL required or non-nullable fields

Non-nullable fields are denoted by an exclamation mark

GraphQL Lists

Lists are denoted by square brackets

GraphQL enum

An enum is a scalar value that has a specified set of possible values

GraphQL interface

  • In GraphQL an interface is a list of fields
  • A GraphQL type must have the same fields as all the interfaces it implements and all interface fields must be of the same type

GraphQL Schema directive

  • A directive allows you to attach arbitrary information to any other schema definition element
  • Directives are always placed behind the element they describe
  • Directives don’t have intrinsic meaning. Each GraphQL implementation can define their own custom directives that add new functionality

GraphQL is the new way of building APIs when you have a challenge to build a Query language for your API

Anil Talla

Written by