[aqap, spring, api, beginners]


You'll have a better experience reading in DEV

Click here to continue reading this post there >>

However, if you want to know more about the project to mirror my posts from DEV here (and why), go ahead and read more.

You can continue to read here too, it's up to you... =]


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

…