DEV Community

Cover image for Complete API in 5 minutes with Spring Data REST - AQAP Series
Bruno Drugowick
Bruno Drugowick

Posted on • Updated on • Originally published at drugowick.dev

Complete API in 5 minutes with Spring Data REST - AQAP Series

#aqap #spring #api #beginners

The following instructions will give you a complete REST API for two related resources in 5 minutes. You will write less than 50 lines of code.

Bootstrap the Project with Spring Initializr

Spring Initializr let's you quickly bootstrap your Spring applications by selecting dependencies. I've already prepared a configuration with the following dependencies:

  • Spring Data JPA to persist data to a database.
  • H2 Database to auto-configure an embedded relational database.
  • Rest Repositories to expose Spring Data repositories over REST.
  • Lombok to reduce boilerplate code and create in compile-time all the Java getters, setters, constructors etc.

Click here to be redirected to Spring Initializr wesite with the previous configuration loaded.

Download, unzip and load the project on your favorite IDE.

Specify the resources

There'll be a resource called User:

@Entity @Data
class User {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private long id;

    private String firstName;
    private String lastName;

    @ManyToOne
    @JoinColumn(name = "role_id")
    private Role role;
}
Enter fullscreen mode Exit fullscreen mode

And another one called Role:

@Entity @Data
class Role {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private long id;

    private String name;
}
Enter fullscreen mode Exit fullscreen mode

Notice the following:

  • @Entity specifies this as a JPA entity to be persisted to a database (in our case, H2).
  • @Data is a Lombok annotation that creates code in compile-time for getters, setters, constructors, toString and hash methods.
  • @Id and @GeneratedValue are JPA annotations that designate the id field as an ID for the entities and that the database IDs will be auto-generated (in this case by the database).
  • @ManyToOne and @JoinColumn relate User and Role entities.

Create and expose repositories

The Repository pattern abstracts the access to read and write data from/to a database. In this little experiment, the entities are to be persisted and the repositories implement the operations to do so.

With Spring Data, though, you won't need any implementation, since it'll be provided to us in runtime. Let's see how:

@RepositoryRestResource(collectionResourceRel = "users", itemResourceRel = "user", path = "users")
interface PersonRepository extends JpaRepository<User, Long> {}

@RepositoryRestResource(collectionResourceRel = "roles", itemResourceRel = "role", path = "roles")
interface RoleRepository extends JpaRepository<Role, Long> {}
Enter fullscreen mode Exit fullscreen mode

Let's break things down:

  • @RepositoryRestResource is what exposes the entities as REST endpoints.
    • itemResourceRel specifies how to call one instance of an entity.
    • collectionResourceRel specifies how to call two or more instances of an entity.
    • path specifies the path (url) to access the resource.
  • extends JpaRepository<... is what provides all the methods to write each entity to the database. The list below was taken with the code completion feature (CTRL + Space on IntelliJ IDEA) on an instance of a repository:

Alt Text

Bootstrap some data

For demonstration purposes, let's create a import.sql file on the resources folder to populate the database with data upon app initialization.

insert into role (name) values ('USER'), ('ADMIN'), ('ROOT');
insert into user (first_name, last_name, role_id) values ('Johnny', 'Bravo', 1), ('Johnny', 'Manso', 2), ('Sidra', 'Cereser', 1), ('Chuck', 'Norris', 3);
Enter fullscreen mode Exit fullscreen mode

Test some operations

Assuming you're running the application on your machine, the following snippets help you "see" the API working.

GET list of resources

On the terminal, type:

curl -i -X GET http://localhost:8080/users
Enter fullscreen mode Exit fullscreen mode

You get:

HTTP/1.1 200 
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/hal+json
Transfer-Encoding: chunked
Date: Tue, 21 Jan 2020 03:02:40 GMT

{
  "_embedded" : {
    "users" : [ {
      "firstName" : "Johnny",
      "lastName" : "Bravo",
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/users/1"
        },
        "user" : {
          "href" : "http://localhost:8080/users/1"
        },
        "role" : {
          "href" : "http://localhost:8080/users/1/role"
        }
      }
    }, {
      "firstName" : "Johnny",
      "lastName" : "Manso",
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/users/2"
        },
        "user" : {
          "href" : "http://localhost:8080/users/2"
        },
        "role" : {
          "href" : "http://localhost:8080/users/2/role"
        }
      }
    }, {
      "firstName" : "Sidra",
      "lastName" : "Cereser",
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/users/3"
        },
        "user" : {
          "href" : "http://localhost:8080/users/3"
        },
        "role" : {
          "href" : "http://localhost:8080/users/3/role"
        }
      }
    }, {
      "firstName" : "Chuck",
      "lastName" : "Norris",
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/users/4"
        },
        "user" : {
          "href" : "http://localhost:8080/users/4"
        },
        "role" : {
          "href" : "http://localhost:8080/users/4/role"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/users{?page,size,sort}",
      "templated" : true
    },
    "profile" : {
      "href" : "http://localhost:8080/profile/users"
    }
  },
  "page" : {
    "size" : 20,
    "totalElements" : 4,
    "totalPages" : 1,
    "number" : 0
  }
}
Enter fullscreen mode Exit fullscreen mode

On the terminal, type:

curl -i -X GET http://localhost:8080/roles
Enter fullscreen mode Exit fullscreen mode

You get:

HTTP/1.1 200 
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/hal+json
Transfer-Encoding: chunked
Date: Tue, 21 Jan 2020 03:10:29 GMT

{
  "_embedded" : {
    "roles" : [ {
      "name" : "USER",
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/roles/1"
        },
        "role" : {
          "href" : "http://localhost:8080/roles/1"
        }
      }
    }, {
      "name" : "ADMIN",
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/roles/2"
        },
        "role" : {
          "href" : "http://localhost:8080/roles/2"
        }
      }
    }, {
      "name" : "ROOT",
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/roles/3"
        },
        "role" : {
          "href" : "http://localhost:8080/roles/3"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/roles{?page,size,sort}",
      "templated" : true
    },
    "profile" : {
      "href" : "http://localhost:8080/profile/roles"
    }
  },
  "page" : {
    "size" : 20,
    "totalElements" : 3,
    "totalPages" : 1,
    "number" : 0
  }
}
Enter fullscreen mode Exit fullscreen mode

GET one resource

On the terminal, type:

curl -i -X GET http://localhost:8080/users/1
Enter fullscreen mode Exit fullscreen mode

You get:

HTTP/1.1 200 
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/hal+json
Transfer-Encoding: chunked
Date: Tue, 21 Jan 2020 03:05:21 GMT

{
  "firstName" : "Johnny",
  "lastName" : "Bravo",
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/users/1"
    },
    "user" : {
      "href" : "http://localhost:8080/users/1"
    },
    "role" : {
      "href" : "http://localhost:8080/users/1/role"
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

On the terminal, type:

curl -i -X GET http://localhost:8080/roles/1
Enter fullscreen mode Exit fullscreen mode

You get:

HTTP/1.1 200 
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/hal+json
Transfer-Encoding: chunked
Date: Tue, 21 Jan 2020 03:11:12 GMT

{
  "name" : "USER",
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/roles/1"
    },
    "role" : {
      "href" : "http://localhost:8080/roles/1"
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

POST a new resource

On the terminal, type:

curl -i -X POST -H "Content-Type:application/json" -d '{"firstName": "Jhon", "lastName": "Benga", "role": "http://localhost:8080/roles/1"}' http://localhost:8080/users
Enter fullscreen mode Exit fullscreen mode

You get:

HTTP/1.1 201 
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Location: http://localhost:8080/users/5
Content-Type: application/hal+json
Transfer-Encoding: chunked
Date: Tue, 21 Jan 2020 03:09:01 GMT

{
  "firstName" : "Jhon",
  "lastName" : "Benga",
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/users/5"
    },
    "user" : {
      "href" : "http://localhost:8080/users/5"
    },
    "role" : {
      "href" : "http://localhost:8080/users/5/role"
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Ahá, did you notice the role property? Yeah, you just send the href property of the role you want to attribute to the user.

Note: this is the reason I didn't include a HAL browser on this article. I don't know how (for now) to properly configure/customize the HAL browser to post embedded entities.

Final thoughts

That was quick, wasn't it? The repository for the application is this:

GitHub logo brunodrugowick / spring-data-rest-example

Example application to serve as a boilerplate and learning purposes for Spring Data REST.

View on GitHub

Here's all the code we wrote for the application:

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

@Entity @Data
class User {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private long id;

    private String firstName;
    private String lastName;

    @ManyToOne
    @JoinColumn(name = "role_id")
    private Role role;
}

@Entity @Data
class Role {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private long id;

    private String name;
}

@RepositoryRestResource(collectionResourceRel = "users", itemResourceRel = "user", path = "users")
interface PersonRepository extends JpaRepository<User, Long> {}

@RepositoryRestResource(collectionResourceRel = "roles", itemResourceRel = "role", path = "roles")
interface RoleRepository extends JpaRepository<Role, Long> {}
Enter fullscreen mode Exit fullscreen mode

AQAP Series

As Quickly As Possible (AQAP) is a series of quick posts on something I find interesting. I encourage (and take part on) the discussions on the comments to further explore the technology, library or code quickly explained here.

Beginners tag

I'm using this tag for the first time. Since there are rules to use it, please let me know if there's something here you (or a beginner) don't understand or that I took for granted and you're (or a beginner may be :) confused about it.

Image by Jason King por Pixabay

Top comments (4)

Collapse
 
brunodrugowick profile image
Bruno Drugowick •

I think it's important to note that I like the idea of having a simple code like that persisting and providing a REST API, but I hate the idea of this architecture scaling to a bigger app without proper app layers segregating the API from the Domain of your app.

This particular post was inspired by Marcelo Bosso saying to me that Node-RED is incomparable when it comes to providing a quick API for a front-end development. =P

Collapse
 
sharadcodes profile image
Sharad Raj (He/Him) •

Love it.... Can you make an article of Spring Boot JWT auth using mongo dB ?

Collapse
 
brunodrugowick profile image
Bruno Drugowick •

Hello, Sharad. On this series I'd probably do two separated articles, one about security and another a about MongoDB.

The one about security may come out soon, I'm researching about it now.

Not sure about writing about MongoDB, but if you want to try something, take a look at docs.spring.io/spring-data/mongodb....

Regards.

Collapse
 
sharadcodes profile image
Sharad Raj (He/Him) •

Exciting

Read next

osmarmontesinos profile image

How to win a hackaton (spoiler: Power of Friendship)

Osmar Montesinos 🇦🇶 -

sanx profile image

Playing with raw image bytes

Sanjay R -

juan_deto profile image

Configure Vitest, MSW and Playwright in a React project with Vite and TS - Part 2

Juan de Tomaso -

hana_sato profile image

Revolutionizing Identity Resolution with Machine Learning: A Technical Overview

Hana Sato -