/ Development

Real World API Series - Part 3: Decisions, Decisions

Sorry for the delay of almost two weeks in between blog posts, but there is a lot going on in my life right now, especially in the evenings. I mean, we have NHL Playoffs, NBA Playoffs, Better Call Saul Season 3, etc. Hey - I never said they were IMPORTANT...I just said there was a lot going on!

In Part 3 of the series, we are going to talk about the decisions we made for our API. We will talk about hosting, technologies and tools. As always, if you missed the previous posts in the series, or just want to refresh your memory, please click the links below.

Part 1: About the Project

Part 2: API 101

So, let's go ahead and get started.

Disclaimer: The decisions made here were made by one small group of senior technology resources, based on their collective experience. However, there are many other technologies and tools that might be better suited for YOUR project, or even OUR project, for that matter. For the sake of everyone, let's not have this devolve into an argument about technologies and tools.

But with that being said, if anyone is interested in the thought process, or why we chose one technology or tool over another, please use the comments for this post, the comments for the cross-post on LinkedIn or contact me directly via [email](mailto: mack.joe@live.com).

Hosting Our API

Like most fledgling enterprises, the cloud is always the best option. Let's not have a Microsoft vs. AWS discussion here. That could take a long time. Suffice it to say I have been working with Azure for a long time, and I prefer it over AWS personally.

AWS has a completely Free Tier that will give you free stuff for a year. Microsoft will give you a $200 credit for signing up, as well as several of their most popular services for free FOREVER. You can explore the offerings and sign up on the Azure Free Signup Page.

However, as someone that works for a Microsoft Partner and that has a MSDN Subscription, I have a $150/month Azure benefit. This benefit allows me to do several things that the free tier does not. For the purposes of this project, it lets me create Azure Web Sites in a higher tier, in terms of performance and features.

So, the API we create is going to be hosted on the Azure Web Sites Platform-as-a-Service (PaaS) offering on Microsoft Azure. When applicable, we will show how to create the things we need on Azure, although the community has far better and more complete examples.

Architecture and Technologies

So, the basic architecture of our API is going to be exactly what you would expect from a modern API.

Database

First, we are going to have a database backend. We have chosen to use MySQL. To be more specific, we are going to use the new Azure Database for MySQL Paas service. I am breaking one of my long-standing rules here and using a PREVIEW Azure service.

Suffice it to say this service looks promising. This allows you to work with one of the most popular RDBMS platforms without needing to worry about supporting physical or virtual hardware, operating systems, or any non-DB-related work. And the tools in the community to work with MySQL are extremely mature, which is a big plus. We will explore our preferred tools later in this post and get everything up, running and configured in the next post in the series.

Framework

Next, let's talk about our main development framework, or the "general contractor" for our little API construction project. We wanted to use Node.js. It's free to use, the community is huge, and there are a plethora of examples online for everything from Hello World to Enterprise Class.

One of the other great things about Node.js is that there are so many packages out there in the community that can drastically shorten your development cycle for certain tasks. Before we get into our choice of packages, I would like to highlight that there are many paths of much less resistance for making an API on Node.js these days than the path we have chosen. The reason for this is that there is a key tradeoff here -- depending on the decisions you make, you can have a shorter development cycle with less control or more control but more work. Unfortunately, it really is that simple.

So, a quick philosophical discussion...I usually gravitate towards somewhere in the middle, in terms of the ease of use vs. granular control tradeoff. I like to take advantage of someone else's hard work when I can, but I like to have finer control over the X's and O's. I also like to look out for frameworks or packages that are overkill for what I am trying to do. Occasionally, you will even come across something that could even be called bloatware.

Packages for Node.js

Disclaimer: based on what we think we know we will need, these are the packages we have researched and come to rest on in our initial architectural and technical planning. As always, we reserve the right to change these at any time, for any reason, with or without revisiting this blog post to update it. After all, as much as we love sharing things here, the point is to end up with a great API not a great, or even good, blog series.

OK - let's talk about the decisions we made for the Node.js packages that will support the development of our API. You can explore all Node.js packages on the Node Package Manager (NPM) site at npmjs.com.

API Helper. First, we wanted a package that would help with some of the API-focused scaffolding while still allowing us to have fine control. We chose hapi. While not quite as mature as Node.js itself, hapi has a robust community that has come up with many plugins to solve common problems. We will explore several of those as we progress through this section.

Authentication. Naturally, we wanted to make sure that our API was able to handle authentication, so we can protect various routes and functionalities from users that should not have access. We decided to use JSON Web Tokens (JWTs) for our authentication mechanism. Luckily, the community has provided us with multiple Node.js packages and hapi plugins to assist. The JWT package/plugin combination that we chose was jsonwebtoken and hapi-auth-jwt.

Encryption. We needed a supporting encryption package to encrypt and decrypt our passwords and JWTs. We decided on bcrypt, which is the generally accepted standard for Node.js encryption.

ORM. We knew that we needed an Object Relational Modeling tool to assist our API in working with MySQL. There are many widely used packages for this, and Sequelize is one of the oldest and best of the group.

Object Validation. Working hand-in-hand with our ODM, we needed a good way to validate web request JSON payloads and objects in our API against the standards we wanted to set. Joi is a great tool for adding object schema description language and validation.

Promise Library. Since we are hoping that our API ends up getting a lot of use...with lots and lots of database operations, we are going to want to use a promise library to ensure that our sequencing is perfect...especially since we are using Node JS. One of my favorite promise libraries for Node is Bluebird.

Working with Files. One of the great things you can do in Node.js, just like many modern frameworks, is add all artifacts of Type X in the same folder, and then just point some simple piece of code at that folder and do something for each file. One great example for Node.js and hapi is to go through the list of all JavaScript route definition files in a "routes" folder and create a route for each one. To suit our purposes here, we will use inert for static file/directory handling and glob for pattern matching.

Templates. Another useful thing that we can do with Node.js and hapi is to provide template for our responses. This can help us simplify our code by templating our responses and maximizing reuse of the templates throughout the API. Vision is a great hapi plugin for using templates.

API Documentation. The standard here is Swagger UI. There are several packages for Node.js and plugins for hapi that help with implementing Swagger UI for your API. Based on our requirements of finding a good mix of features without giving up control, we settled on hapi-swagger.

Error handling. Last, but not least, we wanted to provide some good error handling and messages for our API. A great option for providing HTTP-friendly great error messages in hapi is boom.

Tools

So, I am a Microsoft guy. I am absolutely biased toward Microsoft tools, and with each subsequent release of the toolset from Microsoft, the free versions just keep getting better and better. So, that is the short answer -- I am using all of the free and awesome Microsoft tools that I can get my hands on. When you look at the Microsoft story right now on the DevOps side of things, I have no idea why any enterprise would do anything else. Let's just leave it there - not trying to piss anyone off here.

One side note -- we will not exactly be showing off the enterprise side of the Microsoft tools as we go through this series. I am a lot more interested in showing exactly what anyone that can write code can accomplish with free tools these days.

Database Tools

I really enjoy using HeidiSQL for working with MySQL. I have tried several others over the years and yet I keep ending up working in HeidiSQL.

IDE

The Integrated Development Environment (IDE) for our project will be Microsoft Visual Studio 2017 Community Edition. Of course, it works very well with Azure and Visual Studio Team Services (see below). It even works well with Node.js. You can even have Visual Studio join the party for existing Node.js projects by pointing it to a folder that contains Node.js code. We will try to show multiple scenarios in the Getting Started post that will be coming up next.

In order to show some of the more interesting things you can do for free with Microsoft these days, we will also be trying to show some development happening on a Linux environment from time to time. While full-featured Visual Studio is not available on Linux, there is a less-robust tool, called Visual Studio Code, that can be used on Linux. VS Code is also extremely friendly with the other Microsoft components and Node.js.

Code Repository

We will be using the free version of Visual Studio Team Services (VSTS) for this project. We will show how to set up a simple team project and work with it as a world-class code repository.

DevOps Workflow

GitFlow in Visual Studio to VSTS to Azure and back again. It just works. If you are a developer, think about everything you have been promised but never been delivered from these DevOps and Continuous Development tools in the past. We won't be able to show everything in the free versions, but we will definitely show enough to not only get you started but also get you excited about where the tools are now and where they are heading.

Conclusion

So, hopefully that is enough to get some of you looking forward to the next posts in the series, where we will start playing around with the tools, writing code and building a modern, world-class API from scratch. As always, feel free to use the comments here or on LinkedIn to add to the content.

Joe Mack

Joe Mack

Joe Mack is the creator of this blog. He is an Enterprise Transformation consultant with over 30 years of leadership and technology experience.

Read More