API — Book Genre Operations

Each book must have a specific genre it belongs to. The following API operations are management endpoints to manage book genre items.

Note

There are a lot of preloaded book genres. This happens when the back-end application is deployed for the first time. A Liquibase SQL migration takes place, which creates the database schema and picks up the preload script.

To demonstrate this let’s start by retrieving all existing book genres.

Remember to make use of the access_token obtained in the previous sections.

Get all Book Genres

This request will retrieve all the existing book genres from the system. If no book genres exist then the response will be an empty array: [ ]

1. Perform a GET request:

   curl --location 'http://localhost:8080/genres/books' \
   --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwi....'

2. This should provide a response like:

   [
     {
       "bookGenreID": "c58e0c88-aa81-4442-a165-a8860de86069",
       "genre": "Arts & Entertainment",
       "subGenre": "Art & Architecture"
     },
     {
       "bookGenreID": "40b7c2ed-3b5d-477d-83ab-8ac287f8baac",
       "genre": "Arts & Entertainment",
       "subGenre": "Art History"
     },
     {
       "bookGenreID": "8a5dc039-0df6-42fc-b958-36b522309014",
       "genre": "Arts & Entertainment",
       "subGenre": "Dance"
     },
     ...
   ]

3. The response above shows the first three items, the rest are omitted for brevity.

Create a Book Genre

This endpoint provides functionality to create a new book genre item. It is considered a system operation and thus require elevated user permissions to execute.

The combination of the genre and subGenre items must be unique, otherwise an exception will be thrown.

1. Perform a POST request:

   curl --location 'http://localhost:8080/genres/books' \
   --header 'Content-Type: application/json' \
   --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwi....' \
   --data '{
     "genre": "Professional & Technical",
     "subGenre": "Programming"
   }'

2. This should provide a response like:

   {
     "bookGenreID": "c45a77fd-a0c3-411d-a30a-227d9b6998d3",
     "genre": "Professional & Technical",
     "subGenre": "Programming"
   }

3. The response above shows the newly created book genre. Take note of the bookGenreID value and copy it. In the subsequent sections it will be used as a path parameter.

Get Book Genre by BookGenreID

This endpoint provides functionality to retrieve a specific book genre item by making use of the bookGenreID value as the lookup key. The value is passed along to the back-end application by the means of a path parameter value.

1. Perform a GET request:

   curl --location 'http://localhost:8080/genres/books/c45a77fd-a0c3-411d-a30a-227d9b6998d3' \
   --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwi....'

2. This should provide a response like:

   {
     "bookGenreID": "c45a77fd-a0c3-411d-a30a-227d9b6998d3",
     "genre": "Professional & Technical",
     "subGenre": "Programming"
   }

3. The response above shows the newly created book genre. Take note of the bookGenreID value and copy it. In the subsequent sections it will be used as a path parameter.

Update Book Genre by BookGenreID

This endpoint provides functionality to update an existing book genre item by making use of the bookGenreID value as the lookup key. The value is passed along to the back-end application by the means of a path parameter value.

The request body contents contain the updated values to be applied to the existing item.

1. Perform a PUT request:

   curl --location --request PUT 'http://localhost:8080/genres/books/c45a77fd-a0c3-411d-a30a-227d9b6998d3' \
   --header 'Content-Type: application/json' \
   --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwi....' \
   --data '{
     "genre": "Professional & Technical",
     "subGenre": "Programmings"
   }'

2. There is no response body, and the HTTP status code is HTTP 204 No Content

3. You can run the Get Book Genre by BookGenreID request again to see the difference. The response will show the updated subGenre value which changed from Programming to Programmings.

Delete Book Genre by BookGenreID

This endpoint provides functionality to delete an existing book genre item by making use of the bookGenreID value as the lookup key. The value is passed along to the back-end application by the means of a path parameter value.

Note

You will not be able to delete a book genre if it is allocated to a book. A book must have a genre at all times.

1. Perform a DELETE request:

   curl --location --request DELETE 'http://localhost:8080/genres/books/5465f863-82bb-47cb-9ea3-3d0410a1f39e' \
   --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwi....'

2. There is no response body, and the HTTP status code is HTTP 204 No Content

3. You can run the Get Book Genre by BookGenreID request again to see the difference. The response will return with the HTTP status code of HTTP 404 Not Found as the item has been deleted. The response body will also indicate what went wrong as can be seen below:

   {
     "status": "NOT_FOUND",
     "statusCode": 404,
     "message": "Could not find Book Genre for parameter(s) {bookGenreId=c45a77fd-a0c3-411d-a30a-227d9b6998d3}",
   }

Summary

Endpoints covered in this guide are as follows:

• GET /genres/books
  • Retrieves all book genres found in the system
• POST /genres/books
  • Create a new book genre
• GET /genres/books/<bookGenreID>
  • Retrieves a single book genre by making use of a bookGenreID value
• PUT /genres/books/<bookGenreID>
  • Updates an existing book genre item by making use of a bookGenreID value
• DELETE /genres/books/<bookGenreID>
  • Delete an existing book genre item by making use of a bookGenreID value