A practical approach to creating graphql APIs in node.js - part one (Schemas and Queries)

For a very long time, REST APIs have been the most popular interface for communication between the client and the server.

However, in recent years, Graphql which is developed by Facebook has increasingly come into the limelight.

In this post, I won't be dwelling much regarding the whys and all those theoretical stuff instead, we'll be creating a contact list API for us to get an understanding of the implementation. so here we go

Queries and Schemas
Schemas are the base of every graphql application. They define and describe each data being transferred between the client and the server.
here's the schema for the contact list below:

type Contact {
  name: String!
  phoneNo: String
  address: String!
  id: ID! 
}

type Query {
  countContact: Int!
  allContacts: [Contact!]!
  findContact(name: String!): Contact
}

The above Schema defines two types. The first one being the Contact type with properties name , phoneNo and the rest.

Every property is associated with a type. The name property is a String type which is one of the Scalar types in graphql.

The id field is of type ID which is also a scalar type in graphql that represents a unique Identifier. For simplicity, the ID type is a unique string type.

It is however important to note that all fields but phoneNo in the Contact type must be given a value.This is marked by the exclamation (!) mark on the schema.

The second type defined in the schema is the Query. Every graphql schema contains a Query schema which describes the actions(queries) that can be performed.

The schema defines three queries. countContact return an integer, allContacts returns an array(list) of contact object and findContact takes in a name parameter and returns a contact object.

It is also important to take note of the exclamation(non-null) marks in each query. countContact will surely return an integer field, allContacts will return a list of Contact objects, and the list does not contain any null values, findContact must be given a string parameter and would return a contact object or null.

So the schema describes what queries the client can send to the server, what kind of parameters the queries can have, and what kind of data the queries return.

Query Samples
Assuming we have some data saved already. let's look at some queries we can run and their response.

Of the queries defined in the Query schema the simplest happen to be the countContact

query {
  countContact
}

which will return something like this

{
  "data": {
    "countContact": 1
  }
}

Next would be the allContacts query. While the countContact query was quite simple and straight-forward the allContacts is a bit complicated. This is because it returns a list of Contact objects and in graphql we have to define which fields of the object we want to be returned. There's a huge benefit in this but I won't be going into the details.

query {
  allContacts{
    name
    address
  }
}

Note that you can add or remove any field you want to be returned from the contact object for this sample I'm only selecting the name and address fields

the response would look like this :

{
  "data": {
    "allContacts": [
      {
        "name": "Prince Whyte",
        "address": "Portharcourt Nigeria"
      }
    ]
  }
}

The last query findContact receives a name parameter and returns the details .

query {
  findContact (name: "Prince Whyte") {
    address
    phoneNo
    id
  }
}

_Note that you can add or remove any field you want to be returned from the contact object _

If a record is found the response would be something like this:

{
  "data": {
    "findContact ": {
      "address": "Portharcourt Nigeria",
      "phoneNo": "018267368",
      "id": "4c431436-4650-bc57-11e9-8b80ba53d593"
    }
  }
}

Remember the return value was marked as nullable, so if we search for the details of an unknown

the response would be :

{
  "data": {
    "findContact": null
  }
}

in conclusion here's something i found online concerning Graphql:

As you can see, there is a direct link between a GraphQL query and the returned JSON object. One can think that the query describes what kind of data it wants as a response. The difference to REST queries is stark. With REST, the URL and the type of the request have nothing to do with the form of the returned data.

GraphQL query describes only the data moving between a server and the client. On the server, the data can be organized and saved any way we like.

Despite its name, GraphQL does not actually have anything to do with databases. It does not care how the data is saved. The data a GraphQL API uses can be saved into a relational database, document database, or to other servers which a GraphQL server can access with for example REST.

Next we'll be looking at the apollo-server