GraphQL is a new hype in the Field of API technologies. We have been constructing and using REST API's for quite some time now and started hearing about GraphQL recently. GraphQL is usually described as a frontend-directed API technology as it allows front-end developers to request data in a more simpler way than ever before. The objective of this query language is to formulate client applications formed on an instinctive and adjustable format, for portraying their data prerequisites as well as interactions.
The Phoenix Framework is running on Elixir, which is built on top of Erlang. Elixir core strength is scaling and concurrency. Phoenix is a powerful and productive web framework that does not compromise speed and maintainability. Phoenix comes in with built-in support for web sockets, enabling you to build real-time apps.
- Elixir & Erlang: Phoenix is built on top of these
- Phoenix Web Framework: For writing the web application
- Absinthe: GraphQL toolkit for Elixir for writing queries/mutations
- GraphiQL: An in-browser IDE for exploring GraphQL. You can think of it as a Postman for REST. We will use the mac app from here which is a wrapper around GraphiQL.
The application we will be developing is a simple blog application written using Phoenix Framework with two schemas User and Post defined in Accounts and Blog resp. We will design the application to support API's related to blog creation and management. Assuming you have Erlang, Elixir and mix installed.
Where to Start:
At first, we have to create a Phoenix web application using the following command:
• --no-html - do not generate HTML views.
Note: As we are going to mostly work with API, we don't need any web pages, HTML views and so the command args and
After we create the project, we need to add dependencies in mix.exs to make GraphQL available for the Phoenix application.
Structuring the Application:
We need a few things to structure the GraphQL part of the application :
- GraphQL Schemas : placed in lib/graphql_web/schema/schema.ex folder
- Custom types: We have to define some custom types to be used in schema placed in lib/graphql_web/schema/types.ex
- Resolvers: Schemas map each query or mutation to a resolver function to handle the business logic. Resolvers are placed in their own files. In our case, in lib/graphql/accounts/user_resolver.ex and lib/graphql/blog/post_resolver.ex folder.
Also, we need to modify the router to be able to make queries using the GraphQL client in lib/graphql_web/router.ex and also have to create a GraphQL pipeline to route the API request which also goes inside lib/graphql_web/router.ex:
Writing GraphQL Queries:
Lets write some graphql queries which can be considered to be equivalent to GET requests in REST. But before getting into queries lets take a look at GraphQL schema we defined and its equivalent resolver mapping:
You can see above we have defined four queries in the schema. Lets pick a query and see what goes into it :
Here, we have defined a query to retrieve a particular user using his email address.
- arg(:, ): is the incoming argument which is email and its have to be a non-null string
- Graphql.Accounts.UserResolver.find/2 : is the resolver function that will have the core logic of retrieving a user.
- Accounts_user : is our custom defined resolved type. It’s defined in lib/graphql_web/schema/types.ex as follows:
Once the queries are defined, we need to write the resolver functions. Will go over the resolver function for accounts_user which is present in lib/graphql/accounts/user_resolver.ex file:
This function is used to list all users or retrieve a particular user using an email address. Let’s run it now using GraphiQL browser. You need to have the server running on port 4000. To start the Phoenix server use:
Let’s run a query to retrieve a user using email address:
Here, we are running accountsUser query with an email address to retrieve the id, email, and name fields. GraphQL also supports defining variables which we will show later when writing mutations.
Let’s run another query to list all blog posts:
Writing GraphQL Mutations:
Let's write some GraphQl mutations. If you have understood the way graphql queries are written mutations are much simpler and similar to queries and easy to understand. It is defined in the same form as queries with a resolver function. Different mutations we are gonna write are as follow:
- create_post:- create a new blog post
- update_post :- update a existing blog post
- delete_post:- delete an existing blog post
The mutation looks as follows:
Let's run some mutations to create a post in GraphQL:
Notice the method is POST and not GET over here.
Let's dig into update mutation function :
Here, update post takes two arguments as input , non null id and a post parameter of type update_post_params that holds the input parameter values to update. The mutation is defined in lib/graphql_web/schema/schema.ex while the input parameter values are defined in lib/graphql_web/schema/types.ex —
The difference with previous type definitions is that it’s defined as input_object instead of object.
The corresponding resolver function is defined as follows :
Here we have defined a query parameter to specify the id of the blog post to be updated.
This is all you need, to write a basic GraphQL server for any Phoenix application using Absinthe.