Forem: Calleb Joel Miquissene

GraphQL API Tools and Queries

Calleb Joel Miquissene — Wed, 06 May 2020 15:07:38 +0000

Hello, welcome to another article in the GraphQL + JavaScript series, this is the third article in the series but if you are only interested in the topic of this article, feel free to read because I don't use any of the previous articles as a reference so that you have to go back to them to get some concept.
If you have not read the previous two articles, and want to follow the complete series until the creation of the API, I recommend that you read the first two articles because they have a very important content.
At the end of this article you will know what are the tools of the GraphQL API and also how to make a simple query in a GraphQL API.

Let's do it!

GraphQL API tools

The GraphQL community has already created several open source tools that allow you to interact with the APIs. These tools allow you to write queries using the GraphQL query language and send them to endpoints in order to receive a response in JSON format (in the next article you will understand why responses are received in this format).
In this series I will use the two most popular tools used to test GraphQL queries in a GraphQL API. These tools are: GraphiQL and GraphQL Playground.

1. GraphiQL
Created by Facebook, GraphiQL is one of the most used tools for querying GraphQL APIs.
It is an integrated development environment (IDE) that can be used in the browser or you can download it to your computer.
GraphiQL is a very interactive tool that offers automatic completion (auto-complete), warning in case of errors and allows you to see the results of your queries directly on it.
Most public APIs come with a GraphiQL interface that allows you to query them within the browser.
The GraphiQL interface is composed of two panels. The left panel that allows you to write queries and the right panel that shows you the result of the queries.
In the upper right corner, you can click on Docs to view the service's documentation and learn how to interact with it. This documentation is added to GraphQL automatically because it is read through the service schema.
A schema defines the data available in the service, and GraphiQL automatically creates documentation through a query that it makes to the schema.

2. GraphQL PlayGround
This is another tool widely used to explore GraphQL APIs. It has the same functions as GraphiQL but comes with a few more features and is more fun.
The most interesting feature that GraphQL Playground has, is the ability to send custom HTTP headers, a feature that will be covered in the next articles when we talk about Authorizations.
GraphQL Playground works in the browser, after being given an endpoint so that you can make queries on it. It also has a desktop version that you can download from the website.

GraphQL public APIs
One of the ways you can use to practice queries over a GraphQL API is by using a public API within the tools mentioned above. The same will be done in this series.
You can find many examples of public GraphQL APIs here.

Introduction to GraphQL Queries

(Hehehe finally...)

Queries in the context of GraphQL are operations used to request data from an API. A query is actually an exact description of the data you want to receive from a GraphQL server.
When you send a query, you ask for data units for each field in the query, and if this query is correct, the server sends a JSON response that contains the fields filled with data from the fields you specified in your query.

Whenever a query is executed against a GraphQL server, it is validated against a type system.
Every GraphQL service defines types in a GraphQL schema. You can think of a type system as a blueprint for your API’s data, backed by a list of objects that you define. For example:

type person {
    id: ID!
    name: String
    birthYear: String
    mass: Float 
    height: Float
    gender: String
    eyeColor: String
}

When making a query we must specify which fields exactly we need as an answer.
Suppose we want the name, gender and birth year of the person who has id = 7.
The query would be done as follows:

query {
    person(id:"7"){
        name
        gender
        birthYear
    }
}

And we would have an answer similar to this:

{
    "data":  {
        "person": {
            "name": "Calleb Miquissene",
            "gender": "Male"
            "birthYear: "2000"
        }
    }
}

It is possible to see that the answer is given in JSON format and only the data requested in the query is returned.
Now let's make a query in a public API. I chose API Countries, which has information on continents, and languages based on a list of countries.
When you access the API, it takes you directly to the GraphQL Playground.
By clicking on the Docs tab on the right, you can access the documentation to see the types existing in the API and learn how it works.

Our first query should show the name, capital, currency, continent and language of the country whose id is "MZ".
For this we will make the query based on the existing types in the API.

Query:

query{
  country(code:"MZ"){
    name
    capital
    currency
    continent{
      name
    }
    languages{
      name
    }
  }

}

GraphQL server response:

And we come to the end of another chapter in this series. I hope you liked it!
If you have any comments, doubts or suggestions regarding this article, leave it in the comments and don't forget to leave your ❤!

Understanding GraphQL and its Design Principles

Calleb Joel Miquissene — Tue, 28 Apr 2020 00:03:58 +0000

Welcome to this article!
Now that you know what GraphQL is, its history and how it works, it's time to understand it better.
If you fell randomly in this article, I am pleased to inform you that this is the second article in a series that covers GraphQL and will guide you through the creation of your first GraphQL API using JavaScript.
If you haven't read the first article in the series, you can take a look at it afterwards because it has a very important content in case you want to understand better about the emergence of GraphQL and its operation.
I hope you have a wonderful reading.

What language to use to create my API?

As mentioned in the previous article, GraphQL is a declarative query language, this means that it allows you to query exactly and exclusively the data needed without worrying about how get for them. (It probably may not be very clear now, but I will discuss this point later :)).
GraphQL Server libraries exist for several programming languages including JavaScript, C #, Java, Groovy, .NET, PHP, Scala, Python, Ruby, Erlang, Clojure, Elixir and Go.
The techniques that will be used in this series to build GraphQL services can be applied in any programming language, but this series is focused in the use of JavaScript create them.

GraphQL is actually a specification!
A specification refers to the description of characteristics of a language. The advantage of a specification is that it offers a common vocabulary and good practices for using the language.
GraphQL is a language specification for client-server communication.

GraphQL design principles

It is not because GraphQL allows you to build your API in any way and language you want, that it does not offer you principles for building your service.

Hierarchical
A GraphQL query is hierarchical. Fields are nested within other fields and the query is shaped like the data that it returns.

Product centric
GraphQL is driven by the data needs of the client and the language and runtime that support the client.

Strong typing
A GraphQL server is backed by the GraphQL type system. In the schema, each data point has a specific type against which it will be validated.

Client-specified queries
A GraphQL server provides the capabilities that the clients are allowed to consume.

Introspective
The GraphQL language is able to query the GraphQL server’s type system.

In the next article, you'll see GraphQL in practice, the famous queries and how to do them. For this I will use a public API where we will make our queries.
If you have any questions, suggestions or comments regarding the content covered in this article, leave it in the comments!
If you liked the article don't forget to leave your LIKE ❤!

So what is GraphQL?

Calleb Joel Miquissene — Fri, 24 Apr 2020 02:01:41 +0000

Well, welcome to this "wonderful" article about GraphQL!
If you fell here, you are probably learning about GraphQL or researching it.
This is the first of some articles that I will publish here about GraphQL.
Because of this, and in order to provide you with a delicate reading, I will do my best to explain in detail all the concepts that are likely to cause some doubt regardless of your level of familiarity with the topic covered here ...
For this I will use the redundancy methodology that consists of repeating the same thing in different ways and with different examples in order to place the same content in different parts of your brain!
Tip given, let's do it!

GraphQL History

Chapter 1: Genesis

In 2012, Facebook decided to rebuild its native mobile apps (iOS and Android).
The applications' performance was not very good because they were having constant crashes. At that time, Facebook had a RESTful server and its data was in FQL tables (an SQL version of Facebook).
Due to the problem with their native applications on mobile versions, Facebook engineers realized that the problem was caused by the way the applications received the data.

(Probably they sat down, had a cup of coffee and discussed the problem)

The engineers then decided to improve the way data was being sent to applications.
This decision resulted in a query language that would describe the features and requirements of the data models for the company's client / server applications.

Chapter 2: The big (or misunderstood) battle

In July 2015, the team of Lee Byron, Nick Schrock and Dan Schafer, Facebook engineers, released the first GraphQL specification and the reference for its implementation in JavaScript, called graphql.js.
As of September 2016, it was officially ready for use, although Facebook has been using it in production for a few years.

But, on the other hand, there was the REST created in 2000 and that had been in use for a long time.
REST stands for Representational State Transfer, it relies on a stateless, client-server, cacheable communications protocol -- and in virtually all cases, the HTTP protocol is used. REST is an architecture style for designing networked applications.

When GraphQL came into existence, many programmers believed that it came to replace REST.
The controversy was big and sparked debate at conferences, but calling GraphQL a REST killer is an oversimplification. A more subtle view is that, as the Web has evolved, REST has shown signs of tension under certain conditions. GraphQL was created to alleviate this tension (which will be explained in the next chapters).

How does GraphQL work?

GraphQL is a syntax that describes how to ask for data, and is generally used to load data from a server to a client.
It’s also a runtime for fulfilling queries with your data. The GraphQL service is transport agnostic but is
typically served over HTTP.
The query is nested, and when it is executed, can traverse related objects. This allows us to make one HTTP request for two types of data. We don’t need to make several round trips to drill down into multiple objects. We don’t receive additional unwanted data about those types. With GraphQL, our clients can obtain all of the data they need in one request.

Whenever a query is executed against a GraphQL server, it is validated against a type system. Every GraphQL service defines types in a GraphQL schema. You can think of a type system as a blueprint for your API’s data, backed by a list of objects that you define.

GraphQL is often referred to as a declarative data-fetching language. By that, we mean that developers will list their data requirements as what data they need without focusing on how they’re going to get it. GraphQL server libraries exist in a variety of different languages including C#, Clojure, Elixir, Erlang, Go, Groovy, Java, JavaScript, .NET, PHP, Python, Scala, and Ruby.

If you have any questions or suggestions about this article, feel free to post it in the comments!