Building simple Laravel 5.4 API for Books management with books, readers and librarians – part 1 – designing REST API

General scope for REST API in Laravel 5.4

This series of articles should help you create easily PHP Laravel API using minimum effort and saving your development time.

At the beginning will will focus on list of requirements needed for normal use of system for books management. Main roles and responsibilities will be assigned. All these requirements will be created independently from any physical system implementation.

After that we will define all endpoints in REST API that will enable most of functionality. It is also important to define users and their access to every endpoint.

Later we will map all endpoints into database structure with all fields and tables definitions. All tables relations should also be defined.

At the end we will create Laravel 5.4 project and start working on implementation of all the previous steps.

Main requirements for Rest API

I tried to find most valuable requirements that API should passed and below you can see all of them. This is of course some subset off all possible requriements and feel free to add more of them in your use of system when needed.

  • we should be able to create books
  • we should be able to create users
  • we should have  two types of users:  simple  user and let’s name it reader  and more sophisticated user let’s name it librarian
  • simple user should be able to make reservations and borrow books
  • librarian will be responsible for books and physically booking books for  simple user
  • simple user can cancel any reservation at any moment
  • simple user can make more than one reservation for more books
  • simple user can book a book  only for a month
  • librarian can be able to define all fields for a book
  • if simple user will not receive the book on time he cannot book other books
  • it should be able possible to search through author, title, isbn, year
  • it should be possible to search  through username or email

UML Diagrams showing interactions in booking system

Now when all main requirements are defined we can try to analize what actors are in the system. I selected some of them:

  • Simple User (reader)
  • Librarian

They can interact each other by making some actions. We can name this actions as use cases.

Use cases diagram show us more clearly main interactions that we can observe in the system. It’s definitely easier to understand what is going on.

You can modifly designed by me uml diagram using beatifull system www.draw.io under the link

Mapping UML use cases into REST API Endpoints

Now we are much more closer to define main actions needed in defined by us Rest API. Main endpoits of the API will be joined with such resource:

  • user – standard actions like create, delete, update
  • book – standard actions like create, delete, update
  • book – borrow/return
  • book – search books by different criterias (through different fields of a book)
  • reservation – we can make as many reservations as we want, also we should be able to cancel any reservation at any moment

So let’s start defining every endpoints.

List of endpoints for USER resource

As we defined the list of possible actions to do with user is very simple. We need to have possibility to create full CRUD for user resource.

Method Endpoint and description
POST  /user – creates new user
GET /user – gets collection (list) of users
GET /user/:id – gets user with concrete id
PUT /user/:id – updates user fields
DELETE /user/:id – deletes user by id

List of endpoints for BOOK resource

Endpoints for book looks very similar to user. We add some more parameters especially for borrow and return purposes.

Method Endpoint and description
POST /book – creates new book
GET /book – gets collection (list) of users
GET /book/:id – gets book with concrete id
PUT /book/:id – updates book fields
DELETE /book/:id – deletes book by id
POST /book/borrow/:id – borrows book by id
POST /book/return/:id – returns book by id

Let’s focus on two last endpoints that I created to distinguish the standard book CRUD from additional actions like borrowing and returning. Both this two actions are POST endpoints because we want to make a kind of update on selected book that we borrowed or returned it.

List of endpoints for RESERVATION resource

Reservation resource connect directly books with users. In order to make any reservation we need to be logged as a concrete user (known user_id) then we can make reservation for any book.

Method Endpoint and description
POST /reservation/:user_id/:book_id – creates reservations for user and book
GET /reservation – gets list of all reservations
GET /reservation/:user_id – gets list of all reservations for the selected user
DELETE /reservation/:reservation_id – removes selected reservation

We do not need to define updates actions because user can simple cancel his reservation by removing it. If the action will be needed later than we will add it.

Defining access level for REST API Endpoints

Now we have defined all entpoints in our REST API. The only question we should make is for access different type of users to endpoints.

I simplify this process and we can requirements and assume that:

  • reader has access to:
    • all information about himself but cannot removes himself (only librarian can remove such user)
    • all information about books but cannot remove, update and delete them
    • reservations created by him (so cannot remove reservations created by another user)
  • librarian has access to all data and can modify/delete everything in the system

Desigining database for REST API

These simple requirements allows us to start desigining our database. We have to synthesize all the information we have and think about what fields should each table have. We also need to design relationships between the tables.

So let’s start from preparing diagrams by wonderfull website: https://dbdiagram.io. Below you can see the draft of designed by me database diagram:

The diagram is also shared here: https://dbdiagram.io/d/5d29c566ced98361d6dc9eb7

You can extend easily the definition of database defining more fields or complicating the logic of REST API in real business application. My intention is not to build too many logic but just to show the main idea and step you need to go through in desiging process.

Finally we can also see the definition of database as a schema:

Table users {
  id int [pk]
  username varchar [not null, unique]
  full_name type [not null]
  email varchar
  password varchar
  created_data varchar
}

Table books {
  id int [pk]
  title varchar [not null]
  isbn varchar
  year int
  return_date varchar
  borrow_date varchar
  is_available boolean
  created_date varchar
}

Table reservations {
  id int [pk]
  book_id int [ref: > books.id]
  user_id int [ref: > users.id]
  created_date varchar
}

In the next post we will create Laravel project and start defining and creating designed database with main endpoints.

Leave a Reply