A hapi API, Part 1: Project Planning and Design

Posted in Server Side Development with REST, API's, hapi.js, Design, Planning on 07 May 2017

Overview

I’ve recently been working on a new project, and realized that the majority of my time over the last few weeks has been spent researching best practices, techniques, and frameworks relating to RESTful API’s. Rather than hoard this newfound knowledge, I’ve decided to distill it into this series.

If you’re unfamiliar with RESTful web services, I encourage you to check out What is REST and related articles at restapitutorial.com. Basically, we build our application by leveraging HTTP and the HTTP verbs., which simplifies design and allows for highly scalable applications.

Currently, the world of API design is dominated by JSON, node.js, and the Express framework. While there are other methods and technologies, this combination has proven to be a stable, scalable, and powerful foundation. One interesting break form this web services trifecta is the hapi framework.

Hapi was born and battle tested at Walmart, and has proven to be highly performant. I find hapi much more enjoyable to write over express, and also much more readable. This is a big deal when working on code that is developed by many team members, and not just by one lone developer.

Throughout the course of this series, we will be building a RESTful API using the hapi framework. This API will then allow us to build a scalable web client, again built with the hapi framework. The app we will be building allows users to register, create and manage rental properties.

General Project Plan

In our increasingly agile world, we’ve become accustomed to developing software without much planning. This works on teams with a strong product owner and a clear backlog, however, we don’t always get such a clear instruction. Furthermore, on small projects, we’re acting as developer, designer, product owner, QA, and more. In such a situation, we will need at least a rudimentary roadmap and strategy for our application.

We will break our application into two components: an API, and a web client. The web client will be built with hapi and will use handlebar templates to format the data from API calls. The API will also be built with hapi and will return data in the form of JSON objects.

We will build the application in stages, following this outline:

  • Part 1: Project Planning and Design
  • Part 2: API Structure and Skeleton
  • Part 3: Database Interactions with Sequelize
  • Part 4: Web Client Structure and Skeleton
  • Part 5: Web Client Templates with Handlebars
  • Part 6: Authentication and Authorization
  • BONUS: API Documentation with Swagger

Planning the API

We don’t need to go through any formal or in-depth analysis to create a plan for our API, but we do need to be aware of the use cases and goals of the application. For our purposes, we need to determine what actions our API needs to support in order to allow users to effectively manage rental properties. For this application, the user will need to:

  • obtain and browse a list of properties
  • browse detailed information on one individual property
  • create a property
  • edit an existing property
  • delete an existing property
  • create an account to start managing properties
  • delete their account and associated data

After determining which actions the API will need to support, we then determine which API endpoints are necessary to facilitate those actions. The actions we’ve listed are simple enough, but some projects can require some fairly involved analysis to discover the right endpoints. In addition to determining the endpoints, we should also start thinking about who should be allowed to access the information. Our endpoints will be as follows:

Endpoint Expected Result Access
GET /properties Return a list of properties Users
POST /properties Create a new property Users
GET /properties/{pID} Return a single property Users
PUT /properties/{pID} Update a single property Users
DELETE /properties/{pID} Delete a single property Users
GET /users Return a list of users Administrators
POST /users Create a new user Public
GET /users/{uID} Return a single user Users
PUT /users/{uID} Update a single user Users
DELETE /users/{uID} Delete a single user Users

From this table, we can see that we will need to support a variety of access roles, as well as ensure that users only interact with their data and not that of other users. Also, note that users have all the privileges of the general public, and that administrators have all the privileges of users.

Conclusion

With a general plan in place and our API sketch complete, we are ready to dive in to the actual development of our API. Watch for Part 2: API Structure and Skeleton coming soon!.