DEV Community: AeroGear

Test GraphQL applications with graphql-testx

Davide Bizzarri — Tue, 03 Dec 2019 15:38:52 +0000

Testing is an essential part of application development. Building an application without tests can lead to many problems in future maintenance.

Tests can be classified into multiple categories. Developers usually divide tests between unit tests and integration tests. Unit tests are the easiest to write and maintain because they are stable and self-contained. Our application can rely on external services therefore we will also have to write integration tests.

Integration tests require a separate environment that can be difficult to set up. When developing a new feature that requires changes to both the client and server, we will need to wait for the server to be available and running before we can start writing the integration tests.

Mocking the server

Because of the difficulty of writing integration tests, you may look into a way to mock the server in order to test the application without mocking its functionality.

Mocking is the practice of creating a fake version of a component so that you can develop and test other parts of your application independently. Mocking your backend is a great way to quickly build a prototype of your frontend and lets you test your frontend without starting up any servers. — Jonas Helfer, Mocking your server with just one line of code

Mocking offers a powerful and flexible way to simulate the server, but it comes with the compromise that query results will be auto-generated by default, and mutations will return one to one or auto-generated data. This doesn't provide you with a realistic way to test the application when it relies on data consistency for some of the internals logics, like caching or conflict resolution.

graphql-testx to the rescue

graphql-testx approaches the problem differently, instead of auto-generating the results, it will generate the CRUD resolvers for each type. All resolvers will read and write data to a database providing data consistency between write and read operations. A practical example of the problem:

const { TestxServer } = require("graphql-testx");
const { request } = require("graphql-request");

(async () => {
 let result;

 // We define our server using a datamodel definition
 const server = new TestxServer(`
   type Foo {
     id: ID!
     bar: String!
   }`);

 await server.start();

 // When the TestxServer start it will create and expose
 // the graphql server to an available random port on localhost,
 // therefore we need to ask the TestxServer the address of the
 // graphql server
 const serverUrl = await server.httUrl();

 // TestxServer will also generate ready to use queries and mutations
 const CREATE_FOO = (await server.getMutations()).createFoo;
 const FIND_ALL_FOOS = (await server.getQueries()).findAllFoos;

 // The create mutation will store the data in the database
 // generate an id for us
 result = await request(serverUrl, CREATE_FOO, { bar: "hello" });
 console.log(result);
 // { createFoo: { id: '1', bar: 'hello' } }

 // Because our data are stored in a database, subsequent queries
 // will return the same data
 result = await request(serverUrl, FIND_ALL_FOOS);
 console.log(result);
 // { findAllFoos: [ { id: '1', bar: 'hello' } ] }
})();

graphql-testx is using Graphback under the hood to parse the datamodel and generate the GraphQL schema, database, resolvers, client queries, and mutations. This means that the same datamodel definitions rules of Graphback apply also to graphql-testx.

You can print out the generated GraphQL schema and database schema using the server.getGraphqlSchema() and server.getDatabaseSchema()

An offline journey

We started working on graphql-testx to write a scalable and robust integration tests layer for Offix. Offix is a library based on Apollo Graphql that helps developers create offline applications.

From the testing viewpoint, we need to perform one or more mutations while the device or browser is offline, then we put the device back online to send all mutations, and lastly we query the server to ensure that all mutations have been applied correctly.

We initially developed a small GraphQL server with basic queries and mutations that reads and writes into javascript objects, but soon we started to struggling in testing more complex queries and mutations with multiple relationships between types and we were also investing a considerable amount of time in maintaining it.

So we developed graphql-testx to rewrite all tests in fewer lines and
start focusing on adding more complex tests for covering more use cases.
To learn more on how we did it you can try out our Offix example
in the graphql-testx repo.

Graphback - the evolution of the GraphQL ecosystem

Wojtek Trocki — Wed, 28 Aug 2019 10:07:01 +0000

GraphQL was created almost 7 years ago at Facebook to resolve specific problems for the Facebook mobile platform. As Query Language, GraphQL offers transport and data exchange layer between server and client, leaving many implementation details to developers.
When comparing with REST, GraphQL technology has a steep learning curve and many pitfalls waiting for beginner developers looking to embrace it.

GraphQL ecosystem in 2019

Over the years the ecosystem flourished and evolved towards more production-ready use cases. GraphQL stack became more mature and more developers started to create their applications using this technology.

GraphQL evolved thanks to the large community and many supporting libraries. Choosing the right approach in the ocean of the options can be not only overwhelming but also lead to building solutions that will be suboptimal to our domain and our business needs.

Writing a GraphQL application that is secure and performant can still be a challenging task that involves many technical decisions and architecture patterns that need to be applied.

Challenge of building on top of sample apps

GraphQL community offers many example apps and approaches that can be used as a starting point for your project. Quality of those may differ and they can often be outdated. There are very few sample apps that will cover production-ready use cases due to the complexity of the applications.

Covering complex use cases will often require writing a lot of business logic that needs to be later manually removed by developers who want to reuse sample application for their needs.

Sample apps working with your business logic

If you ever worked with simple sample application you may recall how hard is to adjust those to real business cases.

As an alternative to sample apps, developers can rely on frameworks that provide a high level of abstraction. Technologies that offer rapid application development often come at the cost of the maintenance and flexibility that can seriously limit the extensibility of your application server.

Over the years our team focused on developing scalable GraphQL based servers and clients and we are often were asking ourselves:

Can we build an application template that can offer production-ready capabilities and yet is simple enough to work with without extensive learning?

Can we provide our data model as input to the GraphQL engine and benefit autogenerated data access methods?

Answers for these questions led us to the creation of the new GraphQL based ecosystem called Graphback.

Introducing Graphback

The target of Graphback is to make sample applications working with your business logic by utilizing application templates and code generation. Developers can provide GraphQL schema as input and the command-line client will generate data access methods on top of the chosen stack (called template) and databases we support.

Graphback generates Node.JS application with an entire codebase that is editable and can be later deployed to your own server or cloud provider.
By default, Graphback will follow the best patterns and include proven open-source libraries provided by the vibrant GraphQL community. When working with relational databases Graphback will allow users to manage database schema. The real power of Graphback is its code generation engine that can be extended for different needs.

Graphback to resolve major issues in GraphQL community

Graphback helps developers to boost their getting started experience with GraphQL. The Graphback CLI offers different workflows supporting data retrieval from the database and REST endpoints.
Templates allow having different flavors of the GraphQL frameworks like Relay, Apollo, and Prisma for database access. Thanks to templates developers can avail of a fully functional set of libraries that produce business value and work really well together. The community can provide their own templates to contribute to the success of the entire GraphQL ecosystem.

Graphback generated application source code will be always in your full control - no hidden dependencies or any additional limitations included from Graphback runtime. Graphback will generate CRUD data access methods that can be extended into more customized data access functions at any time.

Developers can introduce custom queries and mutations that will generate data access stubs. Thanks to first-class TypeScript support, generated projects offer type safety.

Ecosystem of templates

Graphback builds an ecosystem for developers that can build sample apps as templates that can be extended by additional features and business logic. Graphback templates follow canonical implementations and allow developers to continue development in a traditional way and tweak every aspect of the application.

Not just a GraphQL server

Apart from a fully functional back-end server, developers can choose to generate GraphQL queries for client-side applications. Client-side code can utilize form generators like https://uniforms.tools, giving developers end to end front-end and back-end solutions that will rely on their schema.

Support

Our project is maintained by volunteers who are devoted to constant love and maintenance. You can support us by becoming a Graphback stargazer on GitHub, or by sharing it on social media.

Our GitHub:
https://github.com/aerogear/graphback/

Our website:
http://graphback.dev

Crash course on REST, GraphQL and Graphback #4: Graphback

Michal Stokluska — Tue, 27 Aug 2019 15:24:22 +0000

Graphback

Building software can be sometimes overwhelming. As junior developers, we are often looking for a sample application that can guide us thru complex server and client architectures. However, as a junior dev, we are often facing problems of templates being too complex or too simple, making the learning process more convoluted.

As a software engineer, I always wanted to learn more by building things, while having some form of standard I can base on when building an end to end solutions.

Graphback in a CLI tool that can help build an entire GraphQL server and a client within seconds! It is an open-source project that is currently being available as beta with lots of amazing features to come!

Graphback will generate schema and resolvers along with generating a database structure. It also addresses the difficulty of configuring a GraphQL server from scratch, and I know that our GraphQL server wasn't particularly difficult to set, but imagine how much work we would have if only we had more types in our server! All graphback needs from you is your schema and it will do everything else for you. However, there's a little bit more that you need to know in order to use full graphback potential.

Requirements

We are not going to go deep in everything that Graphback has to offer but it would be handy if you could make yourself familiar with:

However, if you only would like to see how easy it can be to create a GraphQL server, I will explain everything you need to know in this tutorial.

Let's start!

Our very first step is going to be installing Docker. Just follow the steps from here. To give you a brief on Docker, it is a platform that allows building containers that can contain libraries that are required for an application to start. For example, we are going to use Docker as our PostgreSQL provider. Without Docker, you would need to install entire Postgre SQL server on your local machine and then set it up. With docker, all you do is downloading an image of ready to go, out of the box - Postgres!
Once done, to double-check if your docker was installed correctly type:

$ docker -v

Next, create a new folder called graphback
Navigate to that folder and in command line type:

$ npm install -g graphback-cli

To start graphback run following command:

$ graphback init YOUR_PROJECT_NAME

Where YOUR_PROJECT_NAME is your own name of the project.

Choose "apollo-starter-ts".
"No" for example model and PostgreSQL for your database.
Once it's generated, navigate to your newly created project. It is going to be right in your graphback folder.
In new folder navigate to src/resolvers/, there should be only one file here called index.ts and as you can see in this file, there are no resolvers generated just yet.
Now navigate to model/Default.graphql, delete what's in there and paste our own types that we are well used to:

type User {
    id: ID!
    firstName: String!
    lastName: String!
    title: String!
    email: String
}

type Task {
    id: ID!
    title: String!
    description: String!
    status: String!
    assignedTo: [User!]!
}

Now type in your terminal:

$ graphback generate

Next, open your ./src/resolvers/generated/ and witness the power of Graphback!

Open your task.ts and user.ts and look through all the hard work Graphback did for you! I know that the code behind the resolvers might not be understandable to you at the moment but I'm sure with a bit of hard work you will be able to write your resolvers the very same way!

Our next step is to test it out! In your terminal type:

$ docker-compose up

This will launch a docker image that has Postgre SQL and Redis set up. We are not going to worry about it too much, however, docker is a very powerful tool and I'm sure understanding it will give you a huge advantage in the future.

Type in your console:

$ graphback db

This command is going to build a database structure in Postgre SQL database based on your schema.

Next, because Graphback is using Typescript it needs to be compiled before we can run it on our machine. To do that run:

$ npm run build

Build is going to use the build script from package.json which simply
compiles TypeScript code into JavaScript.

Finally, we can run:

$ npm run start

And our server is ready at localhost:4000/graphql! From now on you got access to all of the generated resolvers. You can view all available queries and mutation in the playground by clicking "Schema" sidebar on the right-hand side of the playground!

Graphback also allows for the use of so-called "Directives" which are extensions that can be attached to types and can affect the execution of a query. Let's re-construct our GraphQL server so that we can delete Task, but we can not delete User. To do that just add @delete to our Task type in model/Default.graphql:

type User {
    id: ID!
    firstName: String!
    lastName: String!
    title: String!
    email: String
}

type Task @delete {
    id: ID!
    title: String!
    description: String!
    status: String!
    assignedTo: [User!]!
}

Now let's regenerate our resolvers with:

$ graphback generate

Navigate again to ./src/resolvers/generated and you will have a new delete mutation in task, but not in user. To test it rebuild our database:

$ graphback db

Recompile our code:

$ npm run build

Launch the server and give it a go!

$ npm run start

If you would like a resolver 'Delete' to be created for all your types, navigate to ./config.json file and change delete field value to true:

{
  "dbConfig": {
    "user": "postgresql",
    "password": "postgres",
    "database": "users",
    "host": "127.0.0.1",
    "port": 55432
  },
  "generation": {
    "create": true,
    "update": true,
    "findAll": true,
    "find": true,
    "delete": false, <----------------------------------------
    "subCreate": false,
    "subUpdate": false,
    "subDelete": false,
    "disableGen": false
  },
  "database": "pg"
}

Treat this file like a settings file for Graphback generator. By default delete generation is disabled hence the need for enabling it one by one in our types specification. However, you can change the value of delete to true and it will be autogenerated for all your types! If your familliar with subscriptions try changing subCreate field to true or use @subCreate directive, regenerate server and enjoy subscription resolvers being written for you!

Graphack also allows for inserting your own resolvers! Let's give it a go! Go to ./model/Default.graphql and add our own query userByName:

type User {
    id: ID!
    firstName: String!
    lastName: String!
    title: String!
    email: String
}

type Task @delete {
    id: ID!
    title: String!
    description: String!
    status: String!
    assignedTo: [User!]!
}

type Query {
    userByName(firstName: String!): User!
}

Now we need to regenerate with:

$ graphback generate

And if you navigate to ./src/resolvers/custom you will see userByName.ts file. As it is custom resolver we need to implement it ourselves. Change it to:

import { GraphQLContext } from '../../context'

export const userByName = {
  Query: {
    userByName: (_: any, args: any, context: GraphQLContext) => {
      return context.db.select().from('user').where('firstName', '=', args.firstName)
    }
  }
}

Resolver looks different then the ones we did in previous tutorials as it is written in TypeScript and uses knex to communicate with a database, but the idea is generally the same as in previous GraphQL tutorial.

Next, we need to repeat our 3-step process:

$ graphback db
$ npm run build
$ npm run start

And navigate to localhost:4000/graphql to test it!

Let's test its functionality and execute the following queries and mutations:

Our task query should return all tasks:

However, as our database is empty it will simply return an empty array!

Let's add some data to our database:

As you can see, Grapback generates mutation in a slightly different way than what we have done, but if you think about, it simply takes in another type called taskInput which consists of title description and status while our ID is auto-generate increment!

Now we can add our first user:

Our database consists of a single user and a single task from now on!

We can now check if our queries are working the way they should:

Summary

Graphback offers a lot of features out of the box. This easy to use, amazing, technology - helped me realize how powerful and life-changing software development can be. Writing an entire GraphQL server line by line which can be very time consuming, setting up subscriptions and using directives can take days or weeks to do! While Graphback can generate it for you within seconds! Imagine how powerful this tool can be in the world where developers are doing their best to provide a working prototype of an application as soon as possible, imagine the time saved that will come from typing graphback generate after populating your typeDefs instead of all the planning, coding and testing your back end. You will still need to
implement your custom business logic yourself, but the core functionality will be provided saving you time from writing a lot of boilerplate.

To find out more about Graphback visit: graphback.dev

I hope that you have found this series of tutorials interesting and learned a few things about REST, GraphQL and Graphback. When I was exposed to these technologies for the first time, I had to rethink what I'm doing and reevaluate what I want to learn next in my journey to become a software developer!

Crash course on REST, GraphQL and Graphback #3: GraphQL

Michal Stokluska — Tue, 27 Aug 2019 15:24:07 +0000

GraphQL

GraphQL is a query language invented by Facebook and is an alternative approach to REST for designing and building APIs. Schema is at the center of any GraphQL server and describes functionality available to clients. Schema has types which define:

Relationships between entities - in our case it would be a relationship between users and tasks
Data manipulation and operation that can be executed by the client, in our project those will be for example queries to fetch all users or all tasks, and mutations to delete and add a user or a task.

To build our GraphQL server we are going to use the "Schema First" approach, which basically prioritizes building schema in development. It allows me to visualize the data flow between entities and queries/mutations that I might require! We are also going to use Apollo framework for GraphQL server, a library that helps us connect our GraphQL schema to a node server, which is same as express framework for REST.

Requirements

Rest in 10 minutes completed or downloaded from my REST tutorial github repository.

Let's get started

First, think about the schema, what are our entities going to be? What data are we planning to return? What does the client need? Imagine our project, with tasks and users, our GraphQL types will look something like this:

type User {
    id: ID!
    firstName: String!
    lastName: String!
    title: String!
    email: String
}

type Task {
    id: ID!
    title: String!
    description: String!
    status: String!
    assignedTo: [User!]!
}

We are defining two entities, a User and Task entity. Both have different attributes and return types. A client can access a User object or Task object and from there he can access any of the attributes given, however, assignedTo from Task returns a User object. Exclamation mark simply means Required so in our example of assignedTo - the return type is required to be of type an array of Users.

In your existing server project, use npm to add the following dependencies:

$ npm install apollo-server-express graphql graphql-import

Next, edit our index.js file.

const express = require('express');
const { ApolloServer } = require('apollo-server-express');
const schema = require('./schema');

const app = express();

app.use(express.json());

const server = new ApolloServer({ schema });

server.applyMiddleware({
  app,
  path: '/graphql',
});

const port = 4000;

app.listen(port, () => {
  console.log(`🚀 Server is running at: http://localhost:${port}/graphql`);
});

We no longer need the REST methods so you can delete them. Next, we are adding Apollo Server to our project. Then, applying a schema ( that is yet to be implemented ) to our Apollo Server, finally, we can apply middleware to it, which is express and path - also called - endpoint.

Create a new folder within our server folder, called schema
In schema folder create a file called typeDefs.graphql which is going to hold types that we have specified above. Paste the following code:

type User {
    id: ID!
    firstName: String!
    lastName: String!
    title: String!
    email: String
}

type Task {
    id: ID!
    title: String!
    description: String!
    status: String!
    assignedTo: [User!]!
}

Next, we are adding type Query - which enables query support for given queries, for now, let's keep it simple and stick to our basic two queries, tasks, which allows a client to access a list of all tasks, and users, which allows accessing an entire array of users.

type Query {
    tasks: [Task!]!
    users: [User!]!
}

Next, add another file called resolvers.js into schema folder and paste the following code:

const { tasks, users } = require('../db');

const resolvers = {
  Query: {
    tasks() {
      return tasks;
    },

    users() {
      return users;
    },
  },
};

module.exports = resolvers;

Resolvers are simply functions resolving value for a type from typeDefs. They can return values like Strings, Numbers, Booleans etc. For example, the users resolver must return an array of Users. They are similar to HTTP handler functions that we saw in express, they implement the business logic and return a result.

Create index.js in schema folder and paste following code:

const { importSchema } = require('graphql-import');
const { makeExecutableSchema } = require('graphql-tools');
const resolvers = require('./resolvers');
const typeDefs = importSchema('schema/typeDefs.graphql');

module.exports = makeExecutableSchema({ resolvers, typeDefs });

In this step we have made an executable schema that contains both, our resolvers and typeDefs so it can be used in our index.js

const express = require('express');
const { ApolloServer } = require('apollo-server-express');
const schema = require('./schema'); <-----------------------------

const app = express();

app.use(express.json());

const server = new ApolloServer({ schema });<---------------------

server.applyMiddleware({
  app,
  path: '/graphql',
});

const port = 4000;

app.listen(port, () => {
  console.log(`🚀 Server is running at: http://localhost:${port}/graphql`);
});

You can now save all your changes, run npm start and navigate to http://localhost:4000/graphql. You should see the following:

You have just launched GraphQL playground from your very first GraphQL server! In the left window, you can write your queries and mutations while responses will be displayed on the right-hand side! Let's give it a go and write our very first query:

Line#2 query AnyNameOfQuery - in here you simply specify whether you are about to use query or mutation and you are naming your query/mutation.
Line#3 tasks{ this is the name of our query specified in typeDefs file:

tasks: [Task!]!

Line#4 & 5 specifies what are we interested in. We have specified in our typeDefs that query task is going to return an array of task objects.
Hit the play button in the middle of the playground and you should get the following response:

If you type in more than one query or mutation in the left window, play button should give you an option to choose which query/mutation you would like to execute.

When we execute the query task we have access to the full object, but we might only want a certain part of it! So in our example above, we have requested only title and description from an array of tasks. You might think, why would we set a name of our query if we are using the pre-named query from our typeDefs.
The answer is - we don't have to! But imagine you are working on a client and you want to access tasks twice, once where you are only interested in titles, and other time when you are interested in descriptions only! Naming queries can be very helpful.

Now, let's add assignedTo to our existing query, which is not going to work for now but I would like you to try it anyway to give you a better understanding the duty of the resolvers.

Add assignedTo{ and hit ctrl + space. You should see all the available data that GraphQL can fetch for you, all that information comes from types specified in typeDefs.

Let's say we are interested in firstName and lastName of our users.

Hit play and...an error! Think of our resolvers and typeDefs now:

const { tasks, users } = require('../db');

const resolvers = {
  Query: {
    tasks() {
      return tasks;
    },

    users() {
      return users;
    },
  },
};

module.exports = resolvers;

The reason why it is not working is that we must implement a new resolver to return the user that the task is assigned to.

Let's specify what our assignedTo should do by adding the following code to the resolvers:

const resolvers = {

    Task: {
        assignedTo(task) {
            return users.filter(u => u.id === task.assignedTo);
        },
    },

    Query: {
        tasks() {
            return tasks;
        },

        users() {
            return users;
        },
    },
};

So, when assignedTo is accessed, we are going to filter through an array of users and return a user that has the id of matching assignedTo.

Now our query should work just fine and I recommend you to play a little bit with queries in the playground to get a better understanding of GraphQL.

Next, let's add one more query to our server - let's say we would like our server to accept a user name and return with a User object of that name. First, we need to edit our typeDefs.graphql:

type Query {
    tasks: [Task!]!
    users: [User!]!
    userByName(firstName: String!): User!
}

So our new userByName query is going to take in a string and is going to return a User object to us.

Now into resolvers:

Query: {
        tasks() {
            return tasks;
        },

        users() {
            return users;
        },

        userByName(parent, args, context,){
            return users.filter(u => u.firstName === args.firstName)
        },
    },

What we are doing is equivalent to REST params!

Now restart the server and test our new query in a playground:

I think it would be a great practice for you to enable another query, let's say findUserById - give it a go yourself!

Next, we are going to add our first mutation type! It would be useful if we could add tasks to our database, to start it we need to edit our typeDefs first:

type Mutation {
    addTask(id: ID!, title: String!, description: String!, status: String!, assignedTo: ID!): Task!
}

Our addTask mutation takes in an id, title, description, status, and assignedTo, all fields are required and we want to return new task.

Now to resolvers:

const { tasks, users } = require('../db');

const resolvers = {

    Task: {
        assignedTo(task) {
            return users.filter(u => u.id === task.assignedTo);
        },
    },

    Query: {
        tasks() {
            return tasks;
        },

        users() {
            return users;
        },

        userByName(parent, args, context,){
            return users.filter(u => u.firstName === args.firstName)
        }
    },
    Mutation: {
        addTask(parent, args, context) {
          const newTask = {
            id: args.id,
            title: args.title,
            description: args.description,
            status: args.status,
            assignedTo: args.assignedTo,
          };

            tasks.push(newTask);

            return newTask;
        },
    };
};

module.exports = resolvers;

What we are doing in addTask mutation is:

Creating a new task based on passed in parameters
Push new task to the task array
Return the newly created task

You can view our newly created mutation in action by visiting the playground:

Our second mutation is going to be deleteTask mutation, again we start with typeDefs.graphql file:

removeTask(id: ID!): [Task!]!

Next our resolvers:

const resolvers = {

    Task: {
        assignedTo(task) {
            return users.filter(u => u.id === task.assignedTo);
        },
    },

    Query: {
        tasks() {
            return tasks;
        },

        users() {
            return users;
        },

        userByName(parent, args, context,){
            return users.filter(u => u.firstName === args.firstName)
        }
    },
    Mutation: {
        addTask(parent, args, context) {
          const newTask = {
            id: args.id,
            title: args.title,
            description: args.description,
            status: args.status,
            assignedTo: args.assignedTo,
          };

            tasks.push(newTask);

            return newTask;
        },

        removeTask(parent, args, context) {
            const taskIndex = tasks.findIndex(t => t.id === args.id);

            tasks.splice(taskIndex, 1);

            return tasks;
          },
    }
};

And just like with the first mutation give it a try in the playground!

Summary

I think by now you should have a good idea what you can do with GraphQL and what is the difference between GraphQL and REST - all those queries and mutations we went through used one endpoint and the client dictates what he wants from the server which can hugely improve the speed of our responses! Another huge success of GraphQL is that it allows receiving many resources in a single request! Imagine that on one of your pages you need access to both tasks and user - you can do it by sending one query! To me, understanding GraphQL changed the way I look at client-server architecture - simply because I'm finding it so amazing and easy to work with that I regret I only got to know it now! I really do hope you will enjoy it as well!

Now, let's head straight for our last part - absolutely mind-blowing Graphback!

Crash course on REST, GraphQL and Graphback #2: REST

Michal Stokluska — Tue, 27 Aug 2019 15:23:53 +0000

REST in 10 minutes!

On a very high level, REST or Representational State Transfer is an architectural style that separates the client and a server. A client sends requests to a server, and the server responds while their concerns are separated, which means a client has no idea how a server works, all it needs to know is that from a given URL, certain data is accessed.

The server, on the other hand, does not care how many clients are going to request the data from it.

The client uses HTTP methods to access the server, the most common of which are: GET, POST, PUT, DELETE and PATCH.

The tutorial below will give you a glimpse of how to build a typical REST API. We will do that by writing a simple Node.js server with Express. Let's give it a go! You can find a finished version of the tutorial in my Github repo.

Requirements

Node.js installed
Visual Studio Code

Let's get started

Open your Visual Studio Code (VSC) and hit ctrl + ` to open up the terminal
Create a folder called server and navigate to it
Type the following into the terminal:

$ npm init

This will start the npm package creator, feel free to fill in some details but if you want, you can just leave it empty by hitting "Enter" a few times!

Add an index.js file and enter the following code in:

console.log("hello world")

Note: Don't forget to save your work in Visual Studio Code after each code input by clicking ctrl + s

In your package.json file add a start script and if there is an echo script, you can delete it:

 "scripts": {
    "start": "node index.js"
  }

It should look like this:

{
  "name": "server",
  "version": "1.0.0",
  "main": "index.js",
  "license": "MIT",
  "scripts": {
    "start": "node index.js"
  }
}

In your command line type:

$ npm start

You should see the "hello world" output in the terminal! Npm looks through scripts specified in package.json and executes them. Package.json can contain a lot of settings and scripts for your projects, for example, license - MIT means it is a "free software" and anyone can use it. There's a lot of useful stuff you can learn about package.json but let's not go into that now;) Without our "start" script we would have to execute:

$ node index.js

If you are interested you can find more information about scripts here.

Next, we are going to use Express which is massively popular and easy to use framework for building HTTP servers in Node.js. So let's add express dependencies to our project:

$ npm install express

What this command does is simply add express to our dependencies. One of the reasons why we need express installed is because it allows us to use GET, POST, PUT, DELETE and other HTTP methods in a very easy way!

Once that's done, we can finally start up our very first express server! Edit your index.js to look like this:

const express = require('express');

const app = express();

app.get('/_ping', (req, res) => {
  res.send('pong');
});

const port = 4000;
app.listen(port, () => {
  console.log(`Server is listening on port ${port}`);
});

const express = require('express') - we are simply importing express from express dependencies that we have downloaded
const app = express() - we are creating an express app
app.get('/_ping') - this is our very first used HTTP method - GET - which simply expects to GET something once the server is accessed from given URL
res.send('pong') - once our app is accessed on '/_ping' let's send "pong" back to the client!
const port - setting up a port variable to 4000
app.listen(port...) - using the set variable to enable the server to listen for requests on a given port

To summarize, we have set up a Node.js server that is using express. Our server listens on localhost:4000, accepts requests from /_ping and responds with pong.

To test it, in your terminal run:

$ npm start

Next, open your browser, go to http://localhost:4000/_ping and enjoy the power of Node.js and express! Pong should be displayed in your browser! If you want to stay in the terminal:

$ curl localhost:4000/_ping

Note: To use curl start up the server as mentioned above, open another terminal window and then run your curl commands in this window.

Our next step is to add some kind of data. For this purpose, lets mock a database connection. In a typical situation our server would communicate with a database like PostgreSQL, MySQL or Mongo, but for the purpose of this tutorial, let's use a mock database. Create a db.js file and copy following code:

const users = [
    {
      id: '1',
      firstName: 'Michael',
      lastName: 'Stone',
      title: 'Mr',
      email: 'michael@example.com',
    },
    {
      id: '2',
      firstName: 'John',
      lastName: 'Barry',
      title: 'Mr',
      email: 'john@example.com',
    },
    {
      id: '3',
      firstName: 'Mary',
      lastName: 'Savage',
      title: 'Mrs',
      email: 'mary@example.com',
    },
  ];

  const tasks = [
    {
      id: '20',
      title: 'Restocking',
      description: 'please restock soft drinks section',
      status: 'to be completed',
      assignedTo: '1',
    },
    {
      id: '21',
      title: 'Cleaning',
      description: 'please clean your desk!',
      status: 'to be completed',
      assignedTo: '2',
    },
    {
      id: '22',
      title: 'Documentation update',
      description: 'please update our customers details',
      status: 'to be completed',
      assignedTo: '3',
    },
  ];

  module.exports = { users, tasks };

This is a very simple database with only a few users and tasks and each task is assigned to a certain user.

As we want to send the actual data to our client now and not just "pong", add the following lines to our index.js:

const { users, tasks } = require('./db');

Which allows us to access tasks and users objects from db file, and also, add other routes to our index.js:

app.get('/tasks', (req, res) => {
    res.json(tasks);
});

app.get('/users', (req, res) => {
    res.json(users);
});

After adding new routes and restarting the server, visit localhost:4000/users or localhost:4000/tasks from your browser! Or in the terminal, simply type:

$ curl localhost:4000/users

$ curl localhost:4000/tasks

Let's imagine we would like to get a specific user by their name. We can do this by passing in parameters. Let's assume we know the first names of our users and this is how we would like to find them. Add the following GET method to our index.js:

app.get('/users/:userName', (req, res) => {
    res.send(users[users.findIndex(u => u.firstName === req.params.userName)]);
  });

Restart the server and give it a try by using curl or visiting localhost:4000/users/Michael.

$ curl localhost:4000/users/Michael

In your response you should have received details concerning Michael only. As this GET request takes in a parameter, you can just change the URL to any other name that is in our database to pull the record of the required user! Try this in your command line:

$ curl localhost:4000/users/John

Now, let's go through another HTTP method - DELETE! To do that add another method to our index.js:

app.delete('/users/:userName', (req, res) => {
    const indexOfUserToBeDeleted = users.findIndex(u => u.firstName === req.params.userName);
    users.splice(indexOfUserToBeDeleted, 1);
    res.json(users);
});

Restart your server and in the terminal type:

$ curl -X "DELETE" localhost:4000/users/Michael

With DELETE and a very short JavaScript code we are able to delete an item from our array of users!

One last method I would like to go through is POST. POST can be used to input a new object into our array or update the existing one. Let's use it to add a new user object to our users array!

Add a POST method to index.js:

app.post('/users', (req, res) => {
  const user = req.body;
  users.push(user);
  res.json(users);
});

Before we can use the POST method in our API we need to add a JSON body parser to our express app as the POST methods will contain JSON objects that need to be accessed. To do this install:

$ npm install body-parser

Then we have to add body parser to our app in index.js :

const express = require('express');
const { users, tasks } = require('./db');
const bodyParser = require('body-parser'); <------------------

const app = express();

app.use(bodyParser.json());               <------------------
...

Restart the server and run the following curl command:

$ curl -d '{"id":"4", "firstName":"Anne", "lastName":"OBrien", "title":"Ms", "email":"anne@example.com"}' -H "Content-Type: application/json" -X POST http://localhost:4000/users

You should see our newly added user in the response.

Your index.js should look like this:

const express = require('express');
const { users, tasks } = require('./db');
const bodyParser = require('body-parser');

const app = express();
app.use(bodyParser.json());

app.get('/_ping', (req, res) => {
    res.send('pong');
});

app.get('/tasks', (req, res) => {
    res.json(tasks);
});

app.get('/users', (req, res) => {
    res.json(users);
});

app.get('/users/:userName', (req, res) => {
    res.send(users[users.findIndex(u => u.firstName === req.params.userName)]);
});

app.post('/users', (req, res) => {
    const user = req.body;
    users.push(user);
    res.json(users);
});

app.delete('/users/:userName', (req, res) => {
    const indexOfUserToBeDeleted = users.findIndex(u => u.firstName === req.params.userName);
    return res.json(users.splice(indexOfUserToBeDeleted, 1));
});

const port = 4000;
app.listen(port, () => {
    console.log(`Server is listening on port ${port}`);
});

Summary

There you go! Your very first Node.js server that uses Express with REST endpoints. It is very easy and there's a lot more you can do with REST, but I guess my target here was to give you a basic understanding of REST. What you just completed is similar to what I was exposed at the beginning of my adventure in becoming a Software Developer, which is still ongoing 😉

It was also a huge eye-opener for me to help me understand client-server architecture! However, as I'm sure you can imagine now, you need to expose a different endpoint for each data you want to send. Our project has only 2 entities, users and tasks, which is plain and simple but imagine how complex REST could be if you add another 10, 20 or even more entities which need to somehow interact with each other!

Imagine that everything we did so far would need to be accessing the database through, for example, SQL statements. These statements would need to be placed in a different layer of our server to hide business logic! Imagine writing all those REST endpoints for your "dream" application! Not that easy anymore, is it?!

In my next post, let's learn about GraphQL!!

Crash course on REST, GraphQL and Graphback #1: Introduction

Michal Stokluska — Tue, 27 Aug 2019 15:23:37 +0000

Introduction

Hi, my name is Michal and I am a third-year student of BSc in Information Technology at Waterford Institute Of Technology. As a mature person with a little baby and a busy family life in general, it wasn't an easy decision to go back to college, but hey! I did it, and I think it was one of the best decisions I've ever made! I was interested in technology ever since I can remember, however, I only realized that I absolutely love software development during my second year in college. BSc in IT is very interesting and it gives a broad understanding of what IT is all about, however, it doesn't go too deep into programming/software development and while I thought I'm ready to take on any software development jobs out there...I was wrong!
It was only when I found out that Red Hat is looking for interns for the summertime that I had my eyes opened to what software development is really about, but let's leave my Red Hat internship story to another post and focus on what I would like this post to be, which is a very brief, simplified, introduction to:

As this were technologies that opened my eyes to a huge amount of possibilities, we are going to build a simple RESTful Node.js server with Express, then move to GraphQL using Apollo Server Express, then show the magic of Graphback!

Prerequisites

I don't think you really need to much except for some basic Javascript knowledge, be familiar with how arrays work and how to interact with arrays, build basic object and we will cover the rest!

Basic understanding of client-server architecture (Client-Server Architecture)
JavaScript - basic knowledge
NodeJS - basic understanding of Node but not necessary (NodeJS tutorial)
Command line - basic understanding

Setting up!

First, we need to get our code editor, I highly recommend using Visual Studio Code due to its simplicity and lightweight. This is what I'll be using and it will be much easier to follow if what you will see on the screen is going to match screenshots!

Next, as we are going to use Node.js please download it from here

We are going to use npm as a package manager which consists of a command-line client, also called npm, and an online database of public and paid-for private packages called the npm registry. As our project will require dependencies to be installed we need something to manage it - npm will do it for us! Npm is also a default package manager of Node so we don't have to do anything with it just yet.

This should be it for now! Let's start with REST!

Automatically Update Apollo Cache after Mutations

Stephen Coady — Thu, 13 Jun 2019 11:40:44 +0000

Background

The application cache provides developers with a complete local state and the ability to work seamlessly in offline situations. It also allows us to minimise the load on our server. However, with this increased power we inherit increased complexity and corner cases where our application may no longer perform as expected, possibly containing outdated and irrelevant data.

In Apollo Client 2.0 developers can use the InMemoryCache package to provide their client with a fully featured cache solution. This cache can be used to resolve data locally or to reduce the number of calls to your server when you do not need to replicate everything the server knows about. The cache is normalised and provides a GraphQL API under which Queries and Mutations are stored. This is a developer-friendly way to organise data.

A high-level diagram of a typical Apollo Client cache can be seen below.

In the above example, we see that the Apollo Client queries or modifies data from one of two places. Depending on how you have configured your client it will either check the cache first to see if it contains the data you are or looking for, or it will ask the server and then tell the cache about the result. This is the foundation of implementing an offline application where your client can now query and mutate data locally without interacting with a server.

Apollo Client by default tries to keep its cache up to date. As an example, let's pretend we have a getItems Query in our cache which contains a list of items and each of these items has a title field. If we (through a mutation) update the title field of one of these items, then Apollo will ensure that our getItems Query is also updated. This ensures that the next time we run getItems (if, for example, you have a slow or non-existent network connection) we get the most up to date information.

The Problem

This trivial example is handled quite nicely by Apollo. However, this is because Apollo already knows about this object we have updated. What if it is a new object we have just created? Or if we delete an object and need to dereference it everywhere? These cases are a little less trivial. When I began working with Apollo Client and the cache I immediately noticed some common pain points associated with dealing with these use cases. Let's explore how these more complex scenarios are handled and why doing it inside my own application led me to create a generic package which the community could benefit from.

Manual Cache Updates

To handle anything outside of basic cache updates, Apollo gives us the ability to provide our client with custom update functions. If we use the basic "ToDo" app example and we want to add a newly created task to our cache, the code will look something like the following:

apollo.mutate({
  mutation: createTaskMutation,
  variables: item,
  update: (cache, { data }) => {
    try {
      let { allTasks } = cache.readQuery({ query: getTasks });
      allTasks.push(data);
      cache.writeQuery({
        query: getTasks,
        data: {
            'allTasks': allTasks
        }
      });
    } catch (e) {
        // We should always catch here,
        // as the cache may be empty or the query may fail
    }
});

Let's walk through this example and explain what is happening. We have a (prebuilt) mutation named createTaskMutation, and our update function which accepts a cache object and also the returned data object from the result of our mutation. This function then attempts to do three things:

Read the prebuilt getTasks Query from our cache.
Push the new data object to our current list of tasks
Write that query back to the cache with the new data now contained within.

Once this update function has run we will have our updated data locally in our cache. The perfect solution! Not really.

Introducing Complexity

Now that we know how the update function works with a trivial case we can explore something more realistic. What about when we introduce subscriptions or multiple queries that need to be updated?

Subscriptions

If our application is also subscribed to getTasks it is quite possible that the subscription data will return before the result of the mutation. This means the result of the mutation we created could already be in our cache. This instantly makes the above update function much more complicated, as in its current state our allTasks object in our cache will now contain our new task twice. In other words, we need to make sure deduplication is performed on our cache.

We need to adapt the update function to the following:

apollo.mutate({
  mutation: createTaskMutation,
  variables: item,
  update: (cache, { data }) => {
    try {
      let { allTasks } = cache.readQuery({ query: getTasks });
      if (allTasks) {
        if (!allTasks.find(task => task.id === data.id)) {
          allTasks.push(data);
        }
      } else {
        allTasks = [data];
      }
      cache.writeQuery({
        query: getTasks,
        data: {
            'allTasks': allTasks
        }
      });
    } catch (e) {
        // We should always catch here,
        // as the cache may be empty or the query may fail
    }
});

As you can see, we read from the cache but crucially we iterate through its contents before making any changes. If we don't find the result of our mutation already in our cache then we can safely add it.

Multiple Queries

Another problem is when there are multiple Queries in our cache which need to be updated. This can happen when several different Queries return subsets of the same data. For example, if a different Query named userTasks also needs to be updated when a task is added the code will resemble something similar to the following:

apollo.mutate({
  mutation: createTaskMutation,
  variables: item,
  update: (cache, { data }) => {
    try {
      let { allTasks } = cache.readQuery({ query: getTasks });
      if (allTasks) {
        if (!allTasks.find(task => task.id === data.id)) {
          allTasks.push(data);
        }
      } else {
        allTasks = [data];
      }
      cache.writeQuery({
        query: getTasks,
        data: {
            'allTasks': allTasks
        }
      });
      let { userTasks } = cache.readQuery({ query: userTasks });
      if (userTasks) {
        if (!userTasks.find(task => task.id === data.id)) {
          userTasks.push(data);
        }
      } else {
        userTasks = [data];
      }
      cache.writeQuery({
        query: userTasks,
        data: {
            'userTasks': userTasks
        }
      });
    } catch (e) {
        // We should always catch here,
        // as the cache may be empty or the query may fail
    }
});

In the above example we have two queries we need to update, both of which should contain our new ToDo item. Our update function is now becoming incredibly obtuse and is filled with a lot of boilerplate code. Keep in mind that all of this boilerplate is for one mutation. What about when our application contains several mutations and this boilerplate needs to be placed in several different places?

Out of the Box Cache Helpers

Instead of requiring this boilerplate with essentially the same basic three steps each time of read, append, write, I thought it would be a good idea to extract the logic to a separate helper package. These helpers provide a way to generate mutation options in a way that is compatible with Apollo's mutate API. This means for very little overhead developers get the above update function built automatically for any mutation they wish.

Let's take a look at how we can use one of these functions to make sure the cache is kept completely up to date after a mutation. First, we need to install the package:

npm i offix-cache

We can then use it within our application like so:

const { createMutationOptions } = require('offix-cache');

const mutationOptions = {
  mutation: createTaskMutation,
  variables: item,
  updateQuery: {
    query: getTasks
  }
};

const generatedOptions = createMutationOptions(mutationOptions);

apollo.mutate(generatedOptions);

In the example above we need to provide the Query we want updated (in this case getTasks) when the mutation result returns. The generatedOptions object returned then contains an update function which automatically does the deduplication we saw in a previous code example.

Extending this a bit further - what about if, like we previously mentioned, we have several Queries we want to update once our mutation result returns? The API also accepts an array of Queries, so we can pass any which need to be updated. The mutationOptions object then looks like the following:

const mutationOptions = {
  mutation: createTaskMutation,
  variables: item,
  updateQuery: [
    {
      query: getTasks
    },
    {
      query: userTasks,
      variables: { user : 1 }
    }
  ]
};

Once we pass this to createMutationOptions we will then have a set of mutation options where our update function will automatically update several Queries upon receiving a result, all for very low overhead.

In a later post, I will also detail some other nice features which may be of use, like automatic optimistic response generation and subscription helpers. For now, if you would like to see some more advanced use-cases please take a look at the project's readme. Or test it out on npm.

Ionic and the Aerogear Mobile Developer Console on Openshift

Austin Cunningham — Tue, 14 May 2019 22:03:59 +0000

Note: I have tested against the latest release and some of these instructions no longer work as expected, As the MDC is in development will revise article in the future.

I wanted to develop an Ionic mobile application and use the services provide by the Aerogear MDC on Openshift. The getting started guides

Ionic

Openshift(Minishift)

Aerogear Mobile Developer Console

Setting up the Aerogear Mobile Developer Console

I won’t go into setting up Minishift, for the Aerogear Mobile Developer console you clone the repo for the MDC checkout the release tag and run the setup script

git clone https://github.com/aerogear/mobile-developer-console.git
cd mobile-developer-console
git checkout 1.0.0
./scripts/minishift.sh

Note: The script destroys the default Minishift profile and creates a new one

Once finished you should get the following the mobile tab in your service catalog on Openshift.

Next you click on the MDC icon and follow the steps to complete installation, select a project to add the MDC to and don’t bind at this time.

When finished you will be able to access the MDC from the project you deployed it too.

Create a mobile app backend in the Mobile Developer Console

Add the Identity Management Service

Add Identity Management service to the app mobile app. This creates a Keycloak instance and a Postgres server, it does a lot of setup for you like creating realms and setting up the admin user and password.

NOTE: change you admin password at this point

Once Keycloak and Postgres have been deployed you need to bind the identity management service to your mobile back-end.

Creating an Ionic App and using the Identity Management Service

Before starting with the ionic app you need to configure the Keycloak instance this is documented here . Just set the Valid Redirect URIs and the Web Origins to point at the Cordova tabs URL.

On to configuring the ionic app I will use one of the template apps from the ionic getting started guide

ionic start test-ionic tabs
cd test-ionic

Create new file in the ./src directory of your ionic project called mobile-services.json

Copy the contents mobile-services.json from the Mobile Developer Console, your app’s Configuration tab to this new file.

NOTE: Minishift url’s are not public so our auth url don’t work outside of localhost.

Install the following npm packages in your ionic project

npm install @aerogear/app --save
npm install @aerogear/auth --save
npm install @types/node --save-dev

NOTE: I only tested with @aerogear/app 2.3.1
Edit ./src/tsconfig.app.json and add a types “node”, This was a bit of a pain point as you can’t use require without doing this

{
  "extends": "../tsconfig.json",
  "compilerOptions": {
  "outDir": "../out-tsc/app",
  "types": ["node"]
},
  "exclude": [
  "test.ts",
  "**/*.spec.ts"
  ]
}

Add the following section to the ./src/main.ts file

import { enableProdMode } from '@angular/core';
import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';

import { AppModule } from './app/app.module';
import { environment } from './environments/environment';

//==========================add the following lines of code=====================
import { init } from "@aerogear/app";
import { Auth } from "@aerogear/auth";

const appConfig = require("./mobile-services.json");
const app = init(appConfig);

const authService = new Auth(app.config);
//let initOptions = { onLoad: "login-required" };

authService.init({ onLoad: "login-required" })
.then(() => {
    // successful init & authentication
    console.log('keycloak init');
})
.catch((err) => {
    // initialization error
    console.log('keycloak init failure', err);
});

//========================end of code block======================================
if (environment.production) {
  enableProdMode();
}

platformBrowserDynamic().bootstrapModule(AppModule)
  .catch(err => console.log(err));

That it we have now got our application protected by the Identity Management service test by running the ionic app from the root of the project

ionic serve

I am using a user I setup on the Keycloak admin console to sign in.

Myblog