DEV Community: Sam Benskin

3 Reasons I'm Giving Story Points Another Chance

Sam Benskin — Thu, 05 Nov 2020 23:45:56 +0000

In this article I analyse three problems I've had with story points, how I overcame these and became once more reconciled to story points as a measurement of effort. I think I can convince you too.

What are Story Points?

The concept behind story points is fairly simple. Story points are a measure of the relative complexity of a piece of work. The term relative is important here. The principle is that you assign points to each story or task based on how complex you think it is. This can be guided by looking at work you've done before that is the same or similar to this task. You can also look at unrelated tickets; Is it more or less complex than that last ticket?

I'm not going to go into detail of how you then use story points, that's a whole topic for another article.

What's so bad about this? Let's dive in deeper.

Problem 1: Repeatability

Software development is often not a repeated process. You're hired to think and apply your knowledge, experience, skills and understanding of the problem to provide a solution. You are not a factory worker that is employed to do the exact same thing day in, day out.. The process of finding the same or similar work is often impossible. There is usually something different about this task to the last time it was done. If you have the rare scenario where you're doing the same thing over and over; you don't need to do story pointing. Separately, but perhaps more importantly, you need to automate that repeatable task right now.

Problem 2: Estimation is tricky

A famous Agile evangelist researched into the effectiveness of story points for a team he was working with and found no correlation between the story points on a ticket and the time it actually took to deliver the ticket. Big 8 or 13 point tickets sometimes ended up being simple and delivered that day, whereas other 1 point tickets ended up taking weeks. His takeaway was that story pointing was an unreliable method for understanding the time required to implement a task. I think the real lesson learned here is that team really had no idea what they were undertaking and had too many unknowns or assumptions, so had no chance of being able to estimate and deliver reliably.

Problem 3: Points mean prizes

The final issue is around the external view of story points. I'm sad to say I've been in conversations like this:

"Last week the team only delivered 30 points; our velocity is 50 points, what went wrong?? We need them to work harder..."

"Team Alpha did 50 points but Team Zeta did 30 points. We need to find out why Team Zeta aren't working as hard"

This behaviour shows a complete misunderstanding of the intention of story points.

The Solutions

Problems 1 and 2 can be easily resolved through the 3-amigo process

Discover unknown work and remove assumptions

My team use a 3-amigo process to check that work is ready to be undertaken before we add it to our backlog. In this process, at least one developer, tester and product owner/manager meet to discuss the task. We have a ticket template that we refine on a semi-regular basis to make sure we're asking the right questions of the task. If anyone is unsure of an aspect of the task, we create a spike ticket and commit to a timebox suitable to understand this unknown. We work to identify our assumptions around the task and create separate tasks to remove them before this ticket is ready to be added to the backlog.

Having a rigorous task review process initially looks like it would slow you down, take you away from the delivery and make you unproductive, but in reality is acts as a shield for the team, protecting them from the unknowns, assumptions and resulting scope/estimation creep.

Story Points and Velocity are for the team only

Story points should be used as an indicative planning tool and that's it. The sprint is the team's commitment of what work they think they can get done in that time period. The points help drive that conversation and ultimately that commitment.

"Last week we did 30 points. Our previous velocity was 50 points, but now it's gone down to 40. I think we need to be a little more cautious than that this week and only commit to 35 points".

If people outside the team are trying to use that information to judge the performance or effectiveness of that team, then the team needs to work with these people to educate them on the function of story points as a planning tool, not a measure of performance.

Not meeting a commitment is more data for the team to review and understand how to improve. It's not what we want each week, but it's not a reflection of the performance of the team, just that they either were too ambitious or didn't fully understand the work required to meet the commitment. Also don't forget about unforeseen interruptions and other reasons that are outside team's control and are not indicative of the performance of the team.

The team need to use this data to reflect on the past sprints, take learnings from it and use that data to drive the forecasting and next sprint commitment.

Don't give people numbers that they have to (mis)-interpret, give them facts and show you're taking on learnings and will work to improve in the next sprint.

What's the Impact?

In the past I've been stung by the misuse of story points and it almost put me off for life. I've since moved on from that employer and found a fabulous culture in Booking.com that supports my team and lets us run the team how we want to.

I have an experimental mindset that I'm rebuilding so I suggested my team try moving to Scrum from Kanban for a recent project and I'm glad we did. We're using story points and sprints correctly, and almost every week we're hitting our sprint commitment. Our cycle time has improved, and the cycle time variance has dramatically reduced due to this and a combined approach of making each task as small as sensibly possible.

If you've been burned by story points in the past, or have a success story I'd love to hear it, so feel free to get in touch with me on Twitter. Thank you for reading and feel free to check out the other articles on my blog.

The Most Important Metric

Sam Benskin — Tue, 31 Dec 2019 07:13:56 +0000

What is your single most important metric for your team?

Is it new visitors? returning customers? new bookings? sales? margin? EBITDA? Perhaps it's something more specific like average percentage viewed in videos, or engagement in social activities?

In my opinion, the single most important metric for your team is: happiness. Let me explain why.

Whilst it's important to measure your performance, outcomes and contribution to company value, they are all indicators of how the team has performed over the period being examined. What this won't tell you is how they could have performed.

If you'd have pushed them harder, would they have delivered more? As a manager it's traditional to believe that the more you apply your managerial influence and apply pressure, the better your team will perform and the more value they will add to the business. But what is actually more likely to happen is that this can lead to micromanagement, decrease in trust from your team and an overall decrease in measurable outcomes. In other cases, a temporary boost in delivery from these techniques will result in a longer term dip in performance, and ultimately morale. Each time you push them harder, the closer they get to burnout and then everyone loses.

Instead, consider the evidence from Google in Project Aristotle, the study into "what makes a team effective at Google". The study is worth reading in full, but for the purposes of this article I'll briefly summarise their findings.

The key takeaway from the research was the following:

Who is on a team matters less than how the team members interact, structure their work, and view their contributions

I believe this was a ground breaking discovery. For years, managers have attempted to recruit "Rockstar" developers who devote themselves to the business and have the highest technical skills. What they really should have been focussing on, was putting the right people together, in the right environment, working on the right things.

The research concluded that there are five key dynamics that high performing teams displayed versus their counterparts in lower performing teams:

Psychological Safety - Can I take risks without fear? Can I challenge others for discussion not conflict?

Dependability - Can I depend on the other team members and can they depend on me?

Structure & Clarity - Do I know what our team wants to achieve and how we are going to achieve it?

Meaning of Work - Is this personally important to me?

Impact of Work - Does what I do matter? Am I creating change?

When people are given the space to take risks and be vulnerable in the team without fear; teammates that can be depended on and to feel needed by the team; a clear purpose; something important to work on; and something that will have an impact, they are put in a position where they can excel and really deliver all they can for the business.

You should no longer focus on the individual and what needs to be done to make them the best they can be. Instead you should focus on providing the right environment and conditions, and then the team will naturally excel.

How do you know if you're providing the right environment for your team to become effective? By measuring the above 5 key dynamics and most importantly, the happiness of each team member.

Personally, I like to be direct and ask the questions that get to the point. For psychological safety you could simply ask each team member to anonymously rate on a score of 1 (low) to 5 (high) how they feel about each of these statements:

"I feel I can take risks without fear of failure"

"I can openly challenge any team member without fear of reprisal or judgement but with the knowledge that it will generate discussion, not conflict"

As for team happiness, I've yet to find a better question than simply:

"How happy are you feeling?"

It's simple, allows complete flexibility for the individual to consider it and answer how best represents how they are feeling, and it's how they are feeling that truly reflects in what they do and how they do it.

So to adapt a quote from John F. Kennedy:

Ask not what your team can do for you, ask what you can do for your team

Thanks for reading!

This article was originally published on my website under this article: The Most Important Metric

An introduction to Single File Components in VueJS

Sam Benskin — Tue, 12 Jun 2018 07:06:20 +0000

NOTE: Please be aware this article is now out of date as the tech has moved on since I wrote it in 2019.

What are they?

Single File Components are an easy concept to understand. In the past you've had to create three separate files for your component(s):

One HTML file for the structure;
One JavaScript file for the behaviour and dynamic content;
One CSS file for the layout and styling.

The reason for this was to create a separation of concerns. It broke down the application into nice logical structures instead of having behaviour and style inlined with the structure. The designer could work on the styling and the developer could build the structure and behaviour.

This approach still had it's own problems. We ended up with monolithic stylesheets and a mass of javascript files and html files all kept separate from one another. Need that card layout in another app? Good luck digging out the styles, behaviour and structure to copy to another project.

There was also the argument of keeping these logical concepts in separate files. The designer could work on the look and feel, and the developer could work on the behaviour and structure. This became redundant when you use an intelligent version control system that can assist with merge changes from many people. Yet, we still cling on to this concept of separation is better. My opinion is: keep related information together and get people to work together.

Single File Components encapsulate the structure, styling and behaviour into one file. Here's an example file:

<template>
    <div>
        <h1>Welcome!</h1>
        <p>Hello, {{ name }}!</p>
    </div>
</template>

<script>
    module.exports = {
       data: function() {
           return {
               name: 'Sam'
           }
       }
    }
</script>

<style scoped>
    p {
        color: #33c689;
        letter-spacing: 3px;
    }
</style>

At first look, it seems strange to have all three parts in one file, but it actually makes a lot more sense.

The "scoped" attribute of the style limits these styles to only apply to this component and it's subcomponents. This means you're free to write changes to global tags without it actually affecting those tags outside this component. Brilliant!

Why?

How often have you had to trawl through pages of CSS to try and find the part you need to work on. Even worse, your component could have it's style taken from many different parts of that file. A class here, an id there, and somewhere in the middle a change to the global functionality of a tag. Not nice to maintain and where do you add new styles if you're trying to be a good developer?

Secondly, the html could have repeated components all over the place, there's no real re-use of structure. This results in mental walls between the styling, structure and behaviour of your component.

Finally, the behaviour, by which we generally mean the JavaScript. Again we're stuck with code split across files as the original developers decided at the time. One project it's all in one file, another it's split by pages, another it's split by domain.

With single file components, there is one place for everything. Easy to read and understand, easy to maintain and easy to develop.

What else?

Single file components are not limited to only support HTML and CSS. You can also use a templating language like pug or a CSS pre-processor like SASS. Here's an example that uses both:

<template lang="pug">
div
  h1 Welcome!
  p Hello, {{name}}
</template>

<script>
module.exports = {
  data: function () {
    return {
      name: 'Sam'
    }
  }
}
</script>

<style lang="sass" scoped>

  $primary-colour: #33c689;
  $letting-spacing: 3px;

  p
    color: $primary-colour;
    letter-spacing: $letting-spacing;
</style>

You're not limited to pug or sass, there's many other options out there: PostCSS, Stylus, TypeScript and more. Anything that has a loader for webpack is supported.

What about React?

React brings together the structure (html) and behaviour (javascript) together in a JSX definition. You could also inline your styling here, but that's generally considered bad practice. This leaves the CSS in separate files again, leaving you in a mess. There are a few libraries out there to allow you to include CSS in your components, but there's no standard. You're likely to see one library in one project, a different library in another project, and no library in the third. This makes it inconsistent and harder to learn.

Why not?

The only downside presented to this approach is that it could result in duplicate styles across different components that aren't directly related to each other. You can avoid or mitigate this with correct usage at styles at the appropriate level. If you have a global theme, put it at the top level component. When you start to feel you're duplicating or copy-pasting lots of styles, this should be a warning. You need to take a step back and think if there is a better place to put these styles to avoid duplication. In some circumstances, you might need to create your own class style at a higher level, and then ue that class on the components that need it.

Summary

I hope that I've whet your appetite around giving Single File Templates a go. If you've never used VueJS before, I strongly recommend also checking out the documentation and there is also a free video course at vueschool.io

Thank you very much for reading my article! If you enjoyed it, please comment to let me know or if you have any suggestions for improvements. Please click the heart/unicorn/bookmark buttons below, I always really appreciate it :)

HowTo: Integrate a MySQL Database into your Java Spring Boot GraphQL Service

Sam Benskin — Wed, 06 Jun 2018 07:19:10 +0000

NOTE: Please be aware this article is now out of date as the tech has moved on since I wrote it in 2019.

In my previous article, HowTo: Build GraphQL Services in Java with Spring Boot, we learnt how to get started with Java Spring Boot and the GraphQL-Tools library. We built a simple endpoint that returned a hard-coded single element array. A great start with only a few files, but it doesn't do very much, so let's add a database.

If you haven't read the first article, I would suggest you do as it sets the basis for this tutorial. I'd suggest going through this tutorial and writing the code yourself as it's a more effective way for most people to learn by doing.

We're going to the Spring Data JPA starter which uses the Java Persistence API to save and retrieve your entity models to/from your chosen database. This API gives you an easy to use abstraction layer so you can use any of a large number of different databases. We're going to use MySQL as it's the most popular database out there.

Pre-requisites

For this guide, you'll need to have MySQL server and client installed. You'll need a privileged user that can create a schema and users. If you don't have this, you need to contact your database administrator to do the first three steps.

Security

Please don't use root in your app, it's a horrendous security issue. We're going to create a non-priviledged user to use with your app.

Don't try to commit these credentials to git because again this is a security risk. I've purposefully added the file to the .gitignore so you don't accidentally do this.

When you want to deploy to another server, you need to manually put the file there. Better still, invest time in understanding and creating an automated build pipeline.

You should never use your production database instance for development. Always have another instance locally on your machine.

Finally, use different credentials for your local and your production environment.

MySQL Setup

First of all, as root or preferably an admin user, login to mysql on the command line:

mysql -uYOUR_PRIVILEGED_USER -p

It will then ask for your password. Once you're in to the MySQL command line, create the schema:

CREATE SCHEMA `graphql_tutorial` DEFAULT COLLATE=`utf8_bin` DEFAULT CHARACTER SET=`utf8`;

And then create a user with access to that schema:

GRANT ALL PRIVILEGES ON `graphql_tutorial`.* TO `graphql_tutorial_user`@`localhost` IDENTIFIED BY 'CHANGE_ME_TO_SOMETHING_SECURE';

Finally, create the table we need:

CREATE TABLE `pets` (`id` INT(11) NOT NULL AUTO_INCREMENT, `name` VARCHAR(255) DEFAULT NULL, `age` TINYINT(3) DEFAULT NULL, `type` ENUM('DOG','CAT','BADGER','MAMMOTH'), PRIMARY KEY(`id`));

Let's create a few entries in the table so we've got something to retrieve:

INSERT INTO `pets` (`name`,`age`,`type`) VALUES ('Steve', 5, 'BADGER'), ('Jeff', 88, 'MAMMOTH'), ('Oscar', 2, 'CAT');

Now let's check everything is in there:

SELECT * FROM pets;

This should show the following result:

+----+-------+------+---------+
| id | name  | age  | type    |
+----+-------+------+---------+
|  1 | Steve |    5 | BADGER  |
|  2 | Jeff  |   88 | MAMMOTH |
|  3 | Oscar |    2 | CAT     |
+----+-------+------+---------+
3 rows in set (0.00 sec)

Great, that's all the MySQL setup done! Type "exit" and press enter to get out of MySQL and back to the command line.

Spring Data JPA

Now we need to add the Spring Data JPA project to our app. Add these lines in your pom.xml in the <dependencies> section:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-jpa</artifactId>
</dependency>
<dependency>
    <groupId>mysql</groupId>
    <artifactId>mysql-connector-java</artifactId>
</dependency>

Then run the install:

mvn install

Now we need to tell our app how to connect to our database. If you've checked-out the github repo, copy the application.properties.example file to application.properties and add in your own URL and credentials. If you haven't, create this file:

src/main/resources/application.properties

And put in this contents

spring.datasource.url=jdbc:mysql://localhost:3306/graphql_tutorial
spring.datasource.username=graphql_tutorial_user
spring.datasource.password=ThePasswordYouCreatedAbove

This sets up our connection URL, the username and the password for Spring Data to connect to your database instance.

Now create this folder to store our repository:

src/main/java/uk/co/benskin/graphql_spring_boot_tutorial/repositories

The repository acts as our interface between the pet model instance and the database table. I'm following the convention of pluralising the database table name that relates to the entity model. So "pets" table for the "Pet" entity model. We'll need to define that in the Entity as the default is just the table name "pet".

Create this file

src/main/java/uk/co/benskin/graphql_spring_boot_tutorial/repositories/PetRepository.java

Then add this contents:

package uk.co.benskin.graphql_spring_boot_tutorial.repositories;

import org.springframework.data.repository.CrudRepository;
import uk.co.benskin.graphql_spring_boot_tutorial.entities.Pet;

public interface PetRepository extends CrudRepository<Pet, Long> {}

If you've never seen the Spring Data JPA classes before, you'll probably be thinking "Is that it?" and yes, that's all you need to create, read, update and delete your entities in a database. Gone is all that boilerplate code you've had to write in the past, brilliant eh?!

Now go back to our Pet entity model and add the @entity, @Table, @id, @GeneratedValue and @Enumerated annotations as below, as well as their imports. You're file should look like the below:

package uk.co.benskin.graphql_spring_boot_tutorial.entities;

import javax.persistence.Entity;
import javax.persistence.EnumType;
import javax.persistence.Enumerated;
import javax.persistence.GeneratedValue;
import javax.persistence.GenerationType;
import javax.persistence.Id;
import javax.persistence.Table;

import lombok.Data;
import uk.co.benskin.graphql_spring_boot_tutorial.enums.Animal;

@Data
@Entity
@Table(name="pets")
public class Pet {
    @Id
    @GeneratedValue(strategy=GenerationType.AUTO)
    private long id;

    private String name;

    @Enumerated(EnumType.STRING)
    private Animal type;

    private int age;
}

Great! Those annotations tell Spring Data JPA that it can persist this entity to the database. We need to tell spring data that our enum is a string otherwise it will default to thinking it's an integer.

Finally we need to update our GraphQL Query resolver in Query.java from a hard-coded array to fetching all pets from the repository. Replace the contents of the file with the following:

package uk.co.benskin.graphql_spring_boot_tutorial.resolvers;

import com.coxautodev.graphql.tools.GraphQLQueryResolver;
import org.springframework.stereotype.Component;

import lombok.RequiredArgsConstructor;
import uk.co.benskin.graphql_spring_boot_tutorial.entities.Pet;
import uk.co.benskin.graphql_spring_boot_tutorial.repositories.PetRepository;

@Component
@RequiredArgsConstructor
public class Query implements GraphQLQueryResolver {

    private final PetRepository PetRepository;

    public Iterable<Pet> pets() {
        return PetRepository.findAll();
    }
}

That's it! Now start up your app again:

mvn spring-boot:start

Navigate to http://localhost:8080/graphiql and you should again see the GraphIQL UI.

Run this query:

{
    pets {
        name,
        age,
        type
    }
}

You should see this result:

{
  "data": {
    "pets": [
      {
        "name": "Steve",
        "age": 5,
        "type": "BADGER"
      },
      {
        "name": "Jeff",
        "age": 88,
        "type": "MAMMOTH"
      },
      {
        "name": "Oscar",
        "age": 2,
        "type": "CAT"
      }
    ]
  }
}

Congratulations, you're now reading all your data from the database!

Thank you very much for reading this article! If you enjoyed it, please comment to let me know or if you have any suggestions for improvements. Please click the heart/unicorn/bookmark buttons below, I always really appreciate it :)

How to Build GraphQL Services in Java with Spring Boot

Sam Benskin — Tue, 22 May 2018 06:47:49 +0000

NOTE: Please be aware this article is now out of date as the tech has moved on since I wrote it in 2019.

Let's start by taking a quick look at the tech involved.

GraphQL

Compared to REST, GraphQL is the new kid on the block, but I think the improvements are so big that I'm moving any new APIs I write to use it. I've seen so many APIs that returned huge amounts of data when all the user needed was a set of identifiers to loop through and query a second endpoint for some other data related to those identifiers, which highlights the second issue. Just writing that sounds mad, I just want to make one call to the API and get everything and only what I need.

I won't go into much detail on why GraphQL is better, there's lots of articles out there that will let you decide that for yourself. All I will say is, there are two big reasons I've decided to make the switch: the ability to easily include in your request the structure of the data you want to receive; and the ability to combine what would have been multiple REST requests into a single GraphQL query. Both are huge improvements over REST. Sure, you could try and write your REST endpoints this way, but then they really wouldn't be REST anymore and GraphQL is built to work this way.

Ok now that is out of the way, let's get on with writing some code. We're going to build a simple barebones GraphQL API in Java using Spring Boot

Spring Boot

Coming from a largely PHP background, I've only recently discovered the joy of the Spring framework and Spring Boot in particular. It makes setting up a new project extremely easy; taking an opinionated view of how to configure and structure a lot of the traditional boilerplate code for controllers, data access, etc, but will get out of the way when you want to configure it how you want. In this example, we won't need to write any controllers; just our entity model, types and the GraphQL schema.

Pre-requisites

For this project, we're going to use Java 8, I tried with Java 10 and then 9, but there's an issue with the lombok dependancy so had to fallback to 8 for this tutorial. I'll update it to 10 when that's fixed. We'll use Spring Boot 2 which uses version 5 of the Spring Framework and sets it all up for you. For simplicity, we'll also use the Maven build framework for managing our java dependencies. We'll also use the excellent GraphQL-Java library spring boot starter to give us the GraphQL and GraphIQL endpoints (more on that later). Finally, I've added Project Lombok which allows you to annotate classes, methods, variables, etc to provide boilerplate functionality.

Here are the exact versions I'll be using:

Let's Go!

First of all, create a new folder and open it in your chosen IDE. I'm using Microsoft Visual Studio Code. It really is the best free code editor out there, sorry Atom.

Create a new file called pom.xml and put this inside:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>uk.co.benskin</groupId>
    <artifactId>graphql_spring_boot_tutorial</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <packaging>jar</packaging>

    <name>graphql_spring_boot_tutorial</name>
    <description>Learn how to build a graphql spring boot based java service</description>

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.0.2.RELEASE</version>
        <relativePath/>
    </parent>

    <properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
        <java.version>1.8</java.version>
    </properties>

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-devtools</artifactId>
        </dependency>
        <dependency>
            <groupId>com.graphql-java</groupId>
            <artifactId>graphql-java-tools</artifactId>
            <version>4.3.0</version>
        </dependency>
        <dependency>
            <groupId>com.graphql-java</groupId>
            <artifactId>graphql-spring-boot-starter</artifactId>
            <version>4.0.0</version>
        </dependency>
        <dependency>
            <groupId>com.graphql-java</groupId>
            <artifactId>graphiql-spring-boot-starter</artifactId>
            <version>4.0.0</version>
        </dependency>
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <version>1.16.20</version>
        </dependency>
    </dependencies>
</project>

The above file defines our project in the first half, so change the project name, description, etc to your own project details. In the second half, we've defined six dependencies:

Spring Boot Web - provides the functionality to support our endpoints through web protocols
Spring Boot DevTools - useful for development building and debugging
GraphQL-Java Tools - Loads and powers our GraphQL schema
GraphQL-Java Spring boot starter for GraphQL - hosts our schema at the /graphql endpoint in our spring context
GraphQL-Java Spring boot starter for GraphIQL - a web based UI for interacting with the /graphql endpoint, with knowledge of the schema at the endpoint
Project Lombok for reducing boilerplate in our java code

Go ahead and install all the dependencies

mvn install

After a large list of output from installing the dependencies for the first time, you should see a message that says "BUILD SUCCESS".

Ok, now we've got everything we need to get started.

Create a folder

src/main/java/uk/co/benskin/graphql_spring_boot_tutorial/

Inside that, create a file

GraphQLSpringBootTutorialApplication.java

Put the following contents

package uk.co.benskin.graphql_spring_boot_tutorial;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class GraphQLSpringBootTutorialApplication {

    public static void main(String[] args) {
        SpringApplication.run(GraphQLSpringBootTutorialApplication.class, args);
    }
}

This loads up a new Spring Applicaton Context integrated automagically with our GraphQL-Java starter dependancies.

Now let's try starting our app and see what we get

mvn spring-boot:run

You should see a lot of info output and hopefully a few lines saying

INFO 64612 --- [  restartedMain] o.s.b.w.embedded.tomcat.TomcatWebServer  : Tomcat started on port(s): 8080 (http) with context path ''
INFO 64612 --- [  restartedMain] b.g.GraphQLSpringBootTutorialApplication : Started GraphQLSpringBootTutorialApplication in 4.886 seconds (JVM

Now open a browser and go to http://localhost:8080

You should see an error page like this

Whitelabel Error Page
This application has no explicit mapping for /error, so you are seeing this as a fallback.

[DATE]
There was an unexpected error (type=Not Found, status=404).
No message available

This is good! the server is running but we've not told how to respond to requests at the root "/", so now try http://localhost:8080/graphiql and you should see a nice UI for interacting with your (yet-to-be-built) endpoint.

Building the GraphQL Schema

Now onto the fun part, the GraphQL schema. I won't go into much detail on how GraphQL works, please take a look at GraphQL tutorials for that.

Create this file

src/main/resources/petshop.graphqls

And put in the contents below

type Query {
    pets: [Pet]
}

type Pet {
    id: Int
    type: Animal
    name: String
    age: Int
}

enum Animal {
    DOG
    CAT
    BADGER
    MAMMOTH
}

Above we've defined the main Query which will return "pets" as an array of Pet types. The type of the Pet is an enum of type Animal, defined below it.

Building the API

Moving back to the java code now. We're going to create a few folders to help us organsie our code. There's no restriction on what you can call these and where you put them, but I strongly suggest you use subfolders to better organise your code, countless future developers will thank you.

Create this folder

src/main/java/uk/co/benskin/graphql_spring_boot_tutorial/enums

And Create this file

src/main/java/uk/co/benskin/graphql_spring_boot_tutorial/enums/Animal.java

And here's the content

package uk.co.benskin.graphql_spring_boot_tutorial.enums;

public enum Animal {
    DOG,
    CAT,
    BADGER,
    MAMMOTH
}

That's defined our enum, now onto the Pet entity model

Create this folder

src/main/java/uk/co/benskin/graphql_spring_boot_tutorial/entities

Create this file

src/main/java/uk/co/benskin/graphql_spring_boot_tutorial/entities/Pet.java

And here's the contents

package uk.co.benskin.graphql_spring_boot_tutorial.entities;

import lombok.Data;
import uk.co.benskin.graphql_spring_boot_tutorial.enums.Animal;

@Data
public class Pet {
    private long id;

    private String name;

    private Animal type;

    private int age;
}

This is a simple POJO with an @data annotation to take care of the boilerplate getters, setters and the constructor.

Now make the directory for the GraphQL resolvers

src/main/java/uk/co/benskin/graphql-spring-boot-tutorial/resolvers

And create the file

src/main/java/uk/co/benskin/graphql_spring_boot_tutorial/resolvers/Query.java

And fill it with this

package uk.co.benskin.graphql_spring_boot_tutorial.resolvers;

import java.util.ArrayList;
import java.util.List;
import com.coxautodev.graphql.tools.GraphQLQueryResolver;
import org.springframework.stereotype.Component;
import uk.co.benskin.graphql_spring_boot_tutorial.entities.Pet;
import uk.co.benskin.graphql_spring_boot_tutorial.enums.Animal;

@Component
public class Query implements GraphQLQueryResolver {

    public List<Pet> pets() {
        List<Pet> pets = new ArrayList<>();

        Pet aPet = new Pet();
        aPet.setId(1l);
        aPet.setName("Bill");
        aPet.setAge(9);
        aPet.setType(Animal.MAMMOTH);

        pets.add(aPet);

        return pets;
    }
}

Ok, that should be everything we need to call our GraphQL endpoint to get a list of pets (one in this case)

Restart your build by stopping maven (ctrl/cmd + c) and starting it again using mvn spring-boot:run

To see it running, go to http://localhost:8080/graphiql and you'll get a nice UI to play around with. Again I won't go into much detail on how to use the GraphIQL interface.

In the box just below the GraphIQL title, to the right of the History box, is where you enter the request. Copy and paste the below there:

{
    pets {
        name
        age
        type
    }
}

Then click the play icon (next to the GraphIQL title). You should see a reponse like below:

{
    "data": {
        "pets": [
            {
                "name": "Bill",
                "age": 9,
                "type": "MAMMOTH"
            }
        ]
    }
}

Congratulations! You've just written a GraphQL service in Java and SpringBoot. Ok so it's not going to return anything else apart from that one record, so in Part 2, we introduce database access through the Spring Data project which utilises the Java Persistence API (JPA)

Thank you very much for reading this article! If you liked it, please comment to let me know or if you have any suggestions for improvements; and make sure to click the heart/unicorn/bookmark buttons below, I always really appreciate it :)

Bootstrap vs Semantic UI vs Bulma for VueJS

Sam Benskin — Fri, 11 May 2018 07:16:11 +0000

Today I'm going to be introducing and comparing three modern front-end CSS based web and mobile frameworks for working alongside VueJS 2.

For each of the frameworks, I've used a companion library written by a third party which makes it easier to use the framework as part of your VueJS projects.

The versions I've tested are:

Bootstrap-vue 1.5.1 (version 2 is coming very soon) with Bootstrap 4.1.1
Semantic-ui-vue 0.2.8 with Semantic UI 2.3.1
Buefy 0.6.5 with Bulma 0.6.2
VueJS 2.5.16

As long as the major versions remain unchanged, this article should still be relevant.

I've included some code samples for items relevant to getting started, but please don't take this as a complete foolproof guide as I've not included everything to start a new project for brevity.

Pre-requisites

For this article you'll need to have nodejs/npm installed (ideally a recent version with the excellent npx binary), parcel and VueJS. Optionally the vue-cli is useful for creating new projects.

Bootstrap

Bootstrap has been around a long time in terms of web development, and the latest incarnation improves upon the excellent framework they've crafted thus far. For many people, it's the default choice.

Version 4 has many improvements and changes, most notably: support for Internet Explorer 8 has been dropped, flexbox support by default, move from less to sass, move from pixels to relative units like rems. Custom builder, glyphicons and grunt have all been dropped; simplying use sass to include what you need from bootstrap, and you're free to choose your own icon set and build tool, although npm scripts are recommended.

Getting started

The guide in the bootstrap-vue docs is quick and easy when you use the vue-cli to start a new project. If you've got a recent version of npm, then you can shorten the number of commands by one by running

npx vue init bootstrap-vue/webpack-simple your-project-name-here

then the usual

cd your-project-name-here
npm install
npm run dev

Easy peasy! I would prefer using parcel to avoid any complex webpack setup, but webpack is more widely known so you'll have more support and you get an autogenerated config file that should be fine for most use cases, so there's no major issue there.

Verdict

It's hard to argue with something that just works brilliantly. If you want a huge amount of community support, themes and customisations, then you're all set with Bootstrap. There's nothing really wrong with it, so if you're happy with bootstrap then I wouldn't recommend changing.

The main downside is that bootstrap still requires jquery for all it's javascript needs. For many people this is fine, but since we're talking about using Vue it seems a shame to have to load jquery for all the bootstrap interactions and have the rest of your app written in the more modern Vue framework. This is just a compromise you'll either have to accept, not use any of the javascript based behaviours or more on to an alternative.

Semantic UI

The goal of Semantic UI is to provide a more natural language orientated approach to styling and interacting with you front-end. The names of the classes make it easier to understand and remember what styles to use, for example, "ui active button" for a semantic ui active button, what could be easier than that?

I'm not a big fan of their docs, the installation page seems complicated, then you're just left with a list of pages on the left with no clue where to start. I would have preferred a proper getting started page after installation that gave you a container, or grid, then some typical starter ui elements like headers, paragraphs, buttons, etc, but that's just personal preference

Getting Started

The process for starting a new project is a little more complicated than with Bootstrap-vue, in that you need to start the project yourself, build the files using gulp, but in reality it's not that big of a deal. The npm installer for semantic ui has a really nice question-answer driven system for getting the files installed where you want them, but personally I would have preferred an opinionated installer that just puts everything in the usual place in the node_modules folder. It's consistent with all other packages and just makes it easier to use it between projects. Keep it simple!

npm install semantic-ui-vue --save
npm install semantic-ui --save

and here's your starter index.js

import Vue from 'vue';
import SuiVue from 'semantic-ui-vue';
import '[path-to-semantic]/dist/semantic.min.css';

/* ... */

Vue.use(SuiVue);

new Vue({
    el: '#app-root',
    render: h => h(App)
});

Then it's just

npx parcel

The problem I encountered was that I had to run gulp watch inside the semantic folder in case of any changes to my customisations, which made it awkward to have that and run parcel for the rest of my project. I'm sure that's a solvable problem and might just have been where I installed semantic ui, so you might have better luck. For me, this left a bit of a bad taste in the mouth. I would assume you could write a gulp file to watch both your sources and the semantic ui files, but I didn't want to have to do that.

Verdict

I love the nomenclature, it feels easier to use when you've only got simple english names for everything. It's a well known framework and there are many themes and customisations but nowhere near the number for Bootstrap. As for downsides; the need to setup gulp manually or parcel differently and that the behaviours utilise jquery are making me lean towards something else, but if you're happy with that and prefer the easier class names, then I would recommend Semantic UI.

Bulma

Bulma is the least well known of the three frameworks I've decided to compare, but this doesn't bother me. I really liked the fact that it's based on flexbox, and that there's no javascript included so you can make a pure Vue (or React) project. Like Semantic UI, they are aiming at easier to remember class names and a simpler usage. For example, to use their grid columns you can simply have a "columns" div containing "column" divs, that's it. They automatically resize according to the number, which is great and really highlights the power of flexbox. For some reason they prefix some of the classes with "is", so you have "button is-primary is-large" which doesn't look quite as nice as Semantic UI but it's no biggie.

Getting Started

The process of getting started using Buefy was nice and easy and worked fine with parcel.

npm install buefy --save

Then your index.js file can start like this

import Vue from 'vue'
import Buefy from 'buefy'
import 'buefy/lib/buefy.css'

Vue.use(Buefy)

new Vue({
    el: '#app',
    render: h => h(App)
});

Customising the theme was also easy, just remember to remove the 3rd import above as it's replaced in your App.vue file. As it's part of your app, there's no need to run gulp or anything else separately to parcel.

Verdict

I really liked Buefy, it was easy to setup and use, but the main downside for me is that there's only a subset of Bulmo implemented in Buefy, so for some code you'll use Buefy components like

<b-checkbox>A checkbox!</b-checkbox>

but for others you'll use classes on divs, for example

<div class="container">...</div>

I assume this is because they don't have any javascript requirements, or that the project just hasn't implemented them, but as it stands I'm not so keen on the mix of the two, it would have been nice to have a consistent set of components to use.

Overall

All three of the frameworks would be a great choice for most projects so really it's down to personal preference. For me, I like the simplicity of Bumla/Buefy so I'm going to give that a go and I'll do an update in future to let you know how it goes.