Complete API in 5 minutes with Spring Data REST - AQAP Series
Tags: aqap, spring, api, beginners
Published: 2020-01-21 03:29:29

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](https://start.spring.io/#!type=maven-project&language=java&platformVersion=2.2.4.RELEASE&packaging=jar&jvmVersion=1.8&groupId=com.example&artifactId=demo&name=demo&description=Demo%20project%20for%20Spring%20Boot%20with%20Spring%20Rest%20Repositories&packageName=com.example.demo&dependencies=data-jpa,lombok,data-rest,h2) 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`:

```java
@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;
}
```

And another one called `Role`:

```java
@Entity @Data
class Role {

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

    private String name;
}
```

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:

```java
@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> {}
```

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](https://thepracticaldev.s3.amazonaws.com/i/teyse3i42kh4wq0683u0.png)

## 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.

```sql
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);
```

# 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: 

```bash
curl -i -X GET http://localhost:8080/users
```

You get:

```json
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
  }
}
```

On the terminal, type:

```bash
curl -i -X GET http://localhost:8080/roles
```

You get:

```json
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
  }
}
```

#### GET one resource

On the terminal, type:

```bash
curl -i -X GET http://localhost:8080/users/1
```

You get:

```json
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"
    }
  }
}
```

On the terminal, type:

```bash
curl -i -X GET http://localhost:8080/roles/1
```

You get:

```json
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"
    }
  }
}
```

#### POST a new resource

On the terminal, type:

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

You get: 

```json
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"
    }
  }
}
```

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 brunodrugowick/spring-data-rest-example %}

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

```java
@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> {}
```

# 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 <a href="https://pixabay.com/pt/users/jaykingsta14-4885997/?utm_source=link-attribution&amp;utm_medium=referral&amp;utm_campaign=image&amp;utm_content=2358636">Jason King</a> por <a href="https://pixabay.com/pt/?utm_source=link-attribution&amp;utm_medium=referral&amp;utm_campaign=image&amp;utm_content=2358636">Pixabay</a>