Design REST API for booking system – part 1
General scope for REST API in Laravel 5.4
This series of articles should help you easily design REST API in PHP Laravel framework using minimum effort and saving your development time. Skills for building quickly any kind of API are especially now very important when everything is decentralized.
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:
[code escaped=”true” lang=”php” ] public function up() { Schema::create(‘users’, function (Blueprint $table) { $table->increments(‘id’); $table->string(‘name’); $table->string(’email’)->unique(); $table->string(‘password’); $table->rememberToken(); $table->timestamps(); }); } public function down() { Schema::dropIfExists(‘users’); } test [/code]
In the next post we will create Laravel project and start defining and creating designed database with main endpoints.
