We will focus on creating REST services for a basic todo management system. We will create services for the following:
Request Methods, Operations, and Uris
One of the best practices of REST services is to use the appropriate HTTP request method based on the action we perform. In the services we exposed until now, we used the GET method, as we focused on services that read data.
The following table shows the appropriate HTTP Request method based on the operation that we perform:
Let's quickly map the services that we want to create to the appropriate request methods:
- Retrieving a list of todos for a given user: This is READ. We will use GET. We will use a URI:
/users/{name}/todos. One more good practice is to use plurals for static things in the URI: users, todo, and so on. This results in more readable URIs. - Retrieving details for a specific todo: Again, we will use
GET. We will use a URI /users/{name}/todos/{id}. You can see that this is consistent with the earlier URI that we decided for the list of todos. - Creating a todo for a user: For the create operation, the suggested HTTP Request method is
POST. To create a new todo, we will post to URI /users/{name}/todos.
To be able to retrieve and store details of a todo, we need a Todo bean and a service to retrieve and store the details.
Let's create a Todo Bean:
We have a created a simple Todo bean with the ID, the name of user, the description of the todo, the todo target date, and an indicator for the completion status. We added a constructor and getters for all fields.
Let's add TodoService now:
Quick things to note are as follows:
- To keep things simple, this service does not talk to the database. It maintains an in-memory array list of todos. This list is initialized using a static initializer.
- We are exposing a couple of simple retrieve methods and a method to add a to-do.
Now that we have the service and bean ready, we can create our first service to retrieve a list of to-do's for a user.
We will create a new RestController annotation called TodoController. The code for the retrieve todos method is shown as follows:
A couple of things to note are as follows:
- We are autowiring the todo service using the
@Autowired annotation - We use the
@GetMapping annotation to map the Get request for the "/users/{name}/todos" URI to the retrieveTodos method
Let's send a test request and see what response we get. The following screenshot shows the output:
The response for the http://localhost:8080/users/Jack/todos URL is as follows:
The code to unit test the TodoController class is shown in the following screenshot:
A few important things to note are as follows:
- We are writing a unit test. So, we want to test only the logic present in the
TodoController class. So, we initialize a Mock MVC framework with only the TodoController class using @WebMvcTest(TodoController.class). @MockBean private TodoService service: We are mocking out the TodoService using the @MockBeanannotation. In test classes that are run with SpringRunner, the beans defined with @MockBean will be replaced by a mock, created using the Mockito framework.when(service.retrieveTodos(anyString())).thenReturn(mockList): We are mocking the retrieveTodos service method to return the mock list.MvcResult result = ..: We are accepting the result of the request into an MvcResult variable to enable us to perform assertions on the response.JSONAssert.assertEquals(expected, result.getResponse().getContentAsString(), false): JSONAssert is a very useful framework to perform asserts on JSON. It compares the response text with the expected value. JSONAssert is intelligent enough to ignore values that are not specified. Another advantage is a clear failure message in case of assertion failures. The last parameter, false, indicates using non-strict mode. If it is changed to true, then the expected should exactly match the result.
The code to perform integration testing on the TodoController class is shown in the following code snippet. It launches up the entire Spring context with all the controllers and beans defined:
This test is very similar to the integration test for BasicController, except that we are using JSONAssert to assert the response.
Retrieving Details for a Specific Todo
We will now add the method to retrieve details for a specific Todo:
A couple of things to note are as follows:
- The URI mapped is
/users/{name}/todos/{id} - We have two path variables defined for
name and id
Let's send a test request and see what response we will get, as shown in the following screenshot:
The response for the http://localhost:8080/users/Jack/todos/1 URL is shown as follows:
The code to unit test retrieveTodo is as follows:
A few important things to note are as follows:
when(service.retrieveTodo(anyInt())).thenReturn(mockTodo): We are mocking the retrieveTodo service method to return the mock todo.MvcResult result = ..: We are accepting the result of the request into an MvcResult variable to enable us to perform assertions on the response.JSONAssert.assertEquals(expected, result.getResponse().getContentAsString(), false): Asserts whether the result is as expected.
The code to perform integration testing on retrieveTodos in TodoController is shown in the following code snippet. This would be added to the TodoControllerIT class:
We will now add the method to create a new Todo. The HTTP method to be used for creation is Post. We will post to a "/users/{name}/todos" URI:
A few things to note are as follows:
@PostMapping("/users/{name}/todos"): @PostMapping annotations map the add() method to the HTTP Request with a POST method.ResponseEntity<?> add(@PathVariable String name, @RequestBody Todo todo): An HTTP post request should ideally return the URI to the created resources. We use ResourceEntity to do this. @RequestBody binds the body of the request directly to the bean.ResponseEntity.noContent().build(): Used to return that the creation of the resource failed.ServletUriComponentsBuilder.fromCurrentRequest().path("/{id}").buildAndExpand(createdTodo.getId()).toUri(): Forms the URI for the created resource that can be returned in the response.ResponseEntity.created(location).build(): Returns a status of 201(CREATED) with a link to the resource created.
If you are on Mac, you might want to try the Paw application as well.
Let's send a test request and see what response we get. The following screenshot shows the response:
We will use Postman app to interact with the REST Services. You can install it from the website, https://www.getpostman.com/. It is available on Windows and Mac. A Google Chrome plugin is also available.
Executing the POST Service
To create a new Todo using POST, we would need to include the JSON for the Todo in the body of the request. The following screenshot shows how we can use the Postman app to create the request and the response after executing the request:
A few important things to note are as follows:
- We are sending a POST request. So, we choose the
POST from the top-left dropdown. - To send the Todo JSON as part of the body of the request, we select the
raw option in the Body tab (highlighted with a blue dot). We choose the content type as JSON (application/json). - Once the request is successfully executed, you can see the status of the request in the bar in the middle of the screen:
Status: 201 Created. - The location is
http://localhost:8080/users/Jack/todos/5. This is the URI of the newly created todo that is received in the response.
Complete details of the request to http://localhost:8080/users/Jack/todos are shown in the block, as follows:
The code to unit test the created Todo is shown as follows:
A few important things to note are as follows:
String todo = "{"user":"Jack","desc":"Learn Spring MVC","done":false}": The Todo content to post to the create todo service.when(service.addTodo(anyString(), anyString(), isNull(), anyBoolean())).thenReturn(mockTodo): Mocks the service to return a dummy todo.MockMvcRequestBuilders.post("/users/Jack/todos").content(todo).contentType(MediaType.APPLICATION_JSON)): Creates a POST to a given URI with the given content type.andExpect(status().isCreated()): Expects that the status is created.andExpect(header().string("location",containsString("/users/Jack/todos/" + CREATED_TODO_ID))): Expects that the header contains location with the URI of created resource.
The code to perform integration testing on the created todo in TodoController is shown as follows. This would be added to the TodoControllerIT class, as follows:
A few important things to note are as follows:
URI location = template.postForLocation(createUrl("/users/Jill/todos"), todo): postForLocation is a utility method especially useful in tests to create new resources. We are posting the todo to the given URI and getting the location from the header.assertThat(location.getPath(), containsString("/users/Jill/todos/4")): Asserts that the location contains the path to the newly created resource.
Free Chapter
