How does GraphQL work?

Abstract

Keywords:

1. Introduction

• Hierarchical - queries look exactly like the data they return.

• Client-specified queries - the client has the liberty to dictate what to fetch from the server,

• Strongly typed - you can validate a query syntactically and within the GraphQL type system before execution. This also helps leverage powerful tools that improve the development experience, such as GraphiQL.

• Introspective - you can query the type system using the GraphQL syntax itself. This is great for parsing incoming data into strongly-typed interfaces, and not having to deal with parsing and manually transforming JSON into objects.

2. Why to use GraphQL?

Single endpoint

• GET: http://hapi.fhir.org/baseDstu3/Patient?_pretty=true, Get lists of all patients.

• GET: http://hapi.fhir.org/baseDstu3/Patient/1427171/_history/1?_pretty=true, Get a single patient resource.

• POST: http://hapi.fhir.org/baseDstu3/Patient/_history/1?_pretty=true, Create a patient record.

• PUT: http://hapi.fhir.org/baseDstu3/Patient/1427171/_history/1?_pretty=true, Update a patients record,

• DELETE: http://hapi.fhir.org/baseDstu3/Patient/1427171/_history/1?_pretty=true, Delete a patient record.

• Best Case: At least create 5 different endpoints as listed above. There are 143 resources listed on HL7 FHIR website, meaning in the best case scenario, one needs to maintain 143 x 5 = 715 endpoints.

• Worst Case: There can be more endpoints to meet custom requirements, for example endpoints to fetch only patients from Bergen, Norway, all patients over 40 years old and many more.

1. Clients requirements are very dynamic. We can not predict requirements of each and every clients. Moreover, each clients requirements are affected by demographics, company’s ethics and rules. Creating or updating existing endpoints every time clients requirements change is inflexible and challenging.

2. Modification of existing endpoints can be risky for existing customers. For example, removing or adding extra attributes to a database table, would require existing customers to modify their request payloads. While it can meet the needs for newer customers, it will create additional tasks for existing customers. At a result of this, RESTful community started API versioning. However, the effect of changes on client, due to API versioning is very costly and challenging. A wonderful article is written about it here [1].

All in all, development and deployment of the GraphQL microservice was extremely quick. They started development in May and it was in production in July. The main reason for this was they didn’t ask for permission and just built it. He highly recommends this approach. It is far better than meetings.” — GraphQL at massive scale: GraphQL as the glue in a microservice architecture, Jason Lengstorf (@jlengstorf) of IBM

Over-fetching

Under-fetching and n+1 request problems

Improved performance

• Reduced payload (clients request only things they need without modifications on the backend)

• Multiple requests combined into one which reduces network overhead

• Client caching and backend batching&caching made easier with tooling

• Prefetching (e.g., Apollo prefetching)

• Optimistic UI updates

Versioning

3. Workflow

• Client Side components

• Server Side components

Server-side components

1. Schema: A GraphQL schema is at the center of any GraphQL server implementation and describes the functionality available to the clients which connect to it.

2. Query: A GraphQL query [2] is the client application request to retrieve data from database or legacy API’s.

3. Resolver: Resolvers provide the instructions for turning a GraphQL operation into data. They resolve the query to data by defining resolver functions. Resolver is a collection of functions that generate response for a GraphQL query. In simple terms, a resolver acts as a GraphQL query handler.

Client-side components

1. GraphiQL: Browser based interface for editing and testing GraphQL queries and mutations.

2. ApolloClient: Best tool to build GraphQL client applications. Integrates well with all javascript front-end.

4. Getting Started with GraphQL

Prerequisite

• Have NodeJS and yarn installed in your system.

1. Here is content for package.json file. All we did is install two libraries apollo-server and graphql.

{
  "name": "graphqlDemo",
  "version": "1.0.0",
  "main": "index.js",
  "license": "MIT",
  "dependencies": {
    "apollo-server": "2.4.8",
    "graphql": "14.2.1"
  }
}

1. Create index.js file and define schema.

const { ApolloServer, gql } = require("apollo-server");
const patient = require("./db");
const typeDefs = gql`
  enum enumNameType {
    official
    usual
    temp
    nickname
    anonymous
    old
    maiden
  }
  enum addressEnumType {
    home
    work
    temp
    old
    billing
  }
  enum addressTypeEnum {
    postal
    physical
    both
  }
  type Patient {
    resourceType: String
    id: ID!
    active: Boolean
    name: [NameSchema]
    gender: String
    address: [AddressSchema]
  }
  type AddressSchema {
    use: addressEnumType
    type: addressTypeEnum
    text: String
    line: String
    city: String
    district: String
    state: String
    postalCode: String
    country: String
  }
  type NameSchema {
    use: enumNameType
    family: String
    given: [String]
  }
  type Query {
    patient: [Patient]
    patientById(id: ID!): Patient
  }
`;
const resolvers = {
  Query: {
    patient: () => patient,
    patientById: (parent, args, context, info) => {
      return patient.filter(item => item.id === args.id)[0];
    }
  }
};
const server = new ApolloServer({ typeDefs, resolvers });
server.listen().then(({ url }) => {
  console.log(`🚀  Server ready at ${url}`);
});

1. Create a mock up database file db.js.

const patient = [
  {
    "resourceType": "Patient",
    "id": "patients0001",
    "active": true,
    "name": [
    {
      "use": "official",
      "family": "Stark",
      "given": [
        "Arya"
      ]
    },
  ],
  "gender": "female",
  "address": [
    {
      "use": "home",
      "type": "physical",
      "text": "The North, Winterfell",
    }
  ],
},
{
    "resourceType": "Patient",
    "id": "patients0002",
    "active": true,
    "name": [
    {
      "use": "official",
      "family": "Snow",
      "given": [
        "Jon"
      ]
    }
  ],
  "gender": "female",
  "address": [
    {
      "use": "home",
      "type": "physical",
      "text": "The North, Winterfell",
    }
  ],
},
{
    "resourceType": "Patient",
    "id": "patients0003",
    "active": false,
    "name": [
    {
      "use": "official",
      "family": "Targaryen",
      "given": [
        "Daenerys"
      ]
    }
  ],
  "gender": "female",
  "address": [
    {
      "use": "home",
      "type": "physical",
      "text": "The Crownlands",
    }
  ],
},
{
    "resourceType": "Patient",
    "id": "patients0004",
    "active": false,
    "name": [
    {
      "use": "official",
      "family": "Lannister",
      "given": [
        "Cersei"
      ]
    }
  ],
  "gender": "female",
  "address": [
    {
      "use": "home",
      "type": "physical",
      "text": "The Westerlands",
    },
    {
      "use": "home",
      "type": "postal",
      "text": "The Crownlands",
    }
  ],
  }
];
module.exports = patient;

1. To run the example, execute follow commands in terminal from root folder of the project.

yarn
node index.js

1. Querying your endpoints.

{
  patient {
    name {
      family
      given
    }
  }
}

{
  patient {
    id
    name {
      family
      given
    }
  }
}

{
  patientById(id: "patients0001") {
    id
    name {
      family
      given
    }
  }
}

Here is link to the second part of the article.

5. Conclusion

References

1. Li, J., Xiong, Y., Liu, X., & Zhang, L. (2013). How does web service API evolution affect clients? In Proceedings - IEEE 20th International Conference on Web Services, ICWS 2013. https://doi.org/10.1109/ICWS.2013.48

2. https://www.tutorialspoint.com/graphql/graphql_mutation.htm.

3. https://graphql.org/learn/