Introducing the Restaurant Booking API
This is the first post in my series of Wednesday publications. My Wednesday publications will be educational, they’ll contain tutorials and practical examples of how to design and build applications. Every week between Thursday and Sunday I’ll publish an exercise, and I’ll publish the solution for the exercise the following Wednesday. Every once in a while the schedule may change, but I’ll do my best to keep producing a consistent stream of educational content every week. The educational section of the newsletter is paid. If you want to subscribe and can’t afford the fee, please let me know and I’ll release a discount code for you. The first project will be building a restaurant booking API.
In the coming months, we’ll implement an API that allows people to book tables in restaurants. We’ll build the API, the database models, the business layer, we’ll add authorization and authentication, a simple UI, and we’ll deploy it to the cloud. We’ll also seek ways to architect the backend so that it’s cloud-native (and I’ll clarify what that means).
The specification for the restaurants booking API is available here. Like all APIs, the restaurant booking API will evolve and change over time. As the time passes, we’ll discover new requirements and we’ll update the design and the specification accordingly. If you’re a student following along with the implementation, I highly encourage you to give feedback about the API design and suggest changes or missing features.
We’ll start the implementation next week by adding the first few endpoints, and we’ll set up the environment and project structure. I’ll also announce the GitHub repository’s URL in next week’s post. In this post, I explain the design of the API and the implementation requirements.
We’ll start with the users, since they’re the ones who’ll be using the API. Restaurant Booking API has two types of users: customers and owners. Customers are users who book tables at the restaurants. They can also review restaurants, upvote or downvote existing reviews, and rate the restaurant’s dishes. Owners are the restaurant owners. Owners can register one or more restaurants under their account and they have specific endpoints to manage the menu. A real-world table booking service would have a lot more functionality, but this is enough to keep us busy for a few weeks.
Restaurant Booking API has three main URL paths:
/restaurants
: allows us to create and manage restaurants, including their menus. Endpoints under this URL path also allow us to make reservations, write reviews, and rate the restaurant’s dishes./owners
: allows us to create and manage restaurant owners’ accounts./customers
: allows us to create and manage customer accounts, manage their reservations, and pull their reviews.
To book a table at a restaurant, customers first query the available time slots through the GET /restaurants/{restaurant_id}/slots
endpoint. When using the slots endpoint, customers must specify the date, number of people, and the amount of time they want to spend dining. To calculate available slots, we look for time ranges with the required number of available seats. At the beginning, we’ll simplify the calculation by working with seats instead of tables, which has limitations. For example, a restaurant may have a table of four seats booked for two people, which means there are two unoccupied seats, but they’re not really available since the table is booked. In a later lesson, we’ll improve on this logic.
To book a table, customers send a request to the POST /restaurants/{restaurant_id}/reservations
endpoint. Reservations have 5 states:
Active: the reservation is confirmed and ready to be served.
Check-in: the user has shown up to the restaurant.
Canceled: the reservation has been canceled. Both owners and customers can cancel a reservation.
Completed: the customer was served.
Noshow: the customer didn’t show up. No shows are a big issue for restaurants, so we must track whether customers show up or not. Owners have access to this information and, and they may decide to cancel reservations from customers with a track record of no shows.
After making a reservation, the status is active. Owners can cancel reservations using the POST /restaurants/{restaurant_id}/reservations/{reservation_id}/cancel
endpoint by giving a valid reason, and customers can cancel through the POST /customers/{customer_id}/reservations/{reservation_id}/cancel
endpoint. When a cancellation happens, we’ll notify customers and owners by email. We’ll create cancellation records in our database so that we can keep track of them in detail.
Cancellations are bad for both customers and businesses, so we’ll allow cancellations up to two days before the date. Later on, we’ll extend the API to allow charging a deposit to confirm a reservation, and we’ll allow restaurant owners to configure the deadline for cancellation.
Cancellations are a red flag, and customers may not want to book restaurants that tend to cancel reservations, while restaurant owners may not want to accept reservations from customers who cancel a lot. Later on, we’ll extend the API to make information about cancellations easily accessible to customers and owners.
When the customer goes to the restaurant, they’ll be able to “check in” their reservation. This proves that they showed up. I haven’t decided how to make this happen yet, but one possibility is to generate a QR code at the time of making the reservation. The QR code is only available to the restaurant owner, who will show the code to the customer when they arrive.
Users can review their experience at the restaurant through the POST /restaurants/{restaurant_id}/reviews
endpoint, and they can rate specific dishes through the POST /restaurants/{restaurant_id}/menu/{dish_id}
endpoint. We can upvote and downvote reviews, and we can also report them if we suspect they are fake or contain inappropriate content. We’ll leverage this information later on to add a feature that allows us to build a concept of customer reputation.
All endpoints are secured except those that allow us to create customer and owner accounts, and those that allow us to get a list of restaurants with their menus and reviews. We’ll authorize access to the API using JWT bearer tokens, and we’ll grant access using Open Authorization flows.
You’ll notice that the API currently only documents successful responses. Obviously, the API will also need to report errors, such as 422 for invalid payloads, 400 for malformed requests, 404 for non-found items, 401 for unauthorized requests, and so on. We’ll extend the API specification later on with this information.
Starting next week, we’ll begin by implementing the first few endpoints of the API, and we’ll set up the environment and project structure. We’ll continue by designing the database, implementing models with SQLAlchemy and managing migrations with Alembic. Then we’ll add a proper business layer and secure the API. Finally, you’ll learn how to test and deploy an API like this. If you have any questions or suggestions at any time, please do let me know!
If you liked this post, you’ll like my book Microservice APIs. Use the code slperalta to obtain a 40% Manning’s website. You can also get the book on Amazon.com.
I’m on a mission to help organizations deliver reliable and secure APIs and microservices. To this end, I run public webinars, I publish content regularly in this newsletter, and I maintain open source projects like fencer, an automated API security testing tool. I streamline my consulting and training efforts through microapis.io. If you work with microservices and APIs and need a consulting or training session, don't hesitate to get in touch directly or arrange a call!