Backend Mock To Go: Swagger meets Node.JS and AWS Beanstalk

Sometime you just need a mock backend for the frontend you’re building. And you need it right now. At least this is what happened in one of my latest projects right after we started to build the frontend.

It was a completely new product, which means that the backend we should work with was just being designed at the time we had to start building the first features. After only two sprints, we had reached the point where further development without having a backend would just be building workarounds and non-testable features. Fortunately, we already had agreed on an API with the backend development team.

In this post i want to walk you through all the steps necessary to create and host a very basic mock backend in just 15 minutes. The mock will be able to serve static JSON content and validate input based on a swagger definition and its example values.

What we will cover in this walkthrough:

1. Revisit our use case and justify this is the right way to mock
2. Generate a Node.js mock from a swagger specification
3. Host our mock on AWS Elastic Beanstalk

What we need and why

In the first story of this series, we already learned about the reasons for creating a mock and about what to consider regarding availability, functionality, flexibility, and effort.

Let’s apply what we learned to our specific use case and double check if using Swagger-codegen and AWS Beanstalk is a good fit for us.

Availability: We need our mock to be available for developers, testers, and product owners.

→ We need to host the mock online. This makes AWS a reasonable choice.

Functionality: The final backend will validate the requests’ input, so the mock should do the same. That way, we can minimize the risk of issues when migrating from our mock to the final backend. We also know that we do not need to keep any state in our mock.

→ We want input to be validated, content can be served from static JSON files since we don’t need any state.

Flexibility: The API is agreed on and it is defined in swagger format. We don’t expect any changes in the API itself. The data being served by the mock should be easy to change though.

→ The API code can be generated once. The JSON data it serves should be easy to update.

Effort / Cost: Our frontend team is already blocked, so the mock has to be ready as soon as possible. Cost for hosting is not an issue.

→ Generating our mock code is fast, we only need a way to quickly host it.

Conclusion:
Since we have the API specified in Swagger format, we can use swagger-codegen to generate the mock in almost every programming language we want. This gives us a functional mock which out of the box validates input based on the schemas in our API definition. The example values in the definition are automatically translated into JSON objects which can be updated easily. AWS Beanstalk is a quick and straightforward way to host web apps. It allows us to have the mock up and running in only a few minutes.

Creating the Mock

For this tutorial, let’s use a very basic sample API that contains some input validation. The mock will contain:

• GET /user/{user_id}
• POST /user

You can find a sample swagger definition in the file user-api.yml in this repository: https://github.com/tobiasbe/backend-mock-beanstalk

If you want to skip the steps necessary to generate the mock’s code and jump right to the deployment step, you can do so. Just clone the whole repository and change directory to user-mock. It contains a ready-to-use mock server based on our user-api.yaml example.

Generate the Code

In order to generate our mock code, we will user swagger’s official swagger-codegen project. It only takes us a few steps to download, build and run.

To get started, download the API definition from the above-mentioned repository and save it in your working directory. Once that’s done, execute the steps below. If you already have swagger-codegen installed, you can skip lines 1–4.

The user-mock directory should now contain a NodeJS project that is ready to be run locally.

Important: In order to make the generated code compatible with how Beanstalk runs Node.js projects, we need to remove the “prestart” script from the package.json file.

// before
"scripts": {
  "prestart": "npm install",  // remove me, please
  "start": "node index.js"
},
// after
"scripts": {
  "start": "node index.js"
}

Run and Test the Mock locally

cd user-mock
npm install
npm start

This will install all necessary dependencies and run the mock server on port 8081. Use your browser and navigate to: http://localhost:8081/docs to see your API’s Swagger UI and try out the requests.

Whenever you send a request using Swagger UI or manually via cURL, one of the functions in $(Project_Root)/services/UsersService.js is being called. This is the place where you can modify the mock’s behavior. We could, for example, remove the sample data from the getUserById function and instead add a static JSON file with a list of users that can be used to find users by id and return a 404 in case the requested user does not exist.

Earlier, I mentioned that the data you send to the endpoints will be validated. Validation is handled by the swagger middleware which is configured in index.js. It validates all incoming requests based on the swagger specification before routing them to the respective controllers. If you would now send a POST request to /users containing a JSON object without the fields name and avatar, the mock would reject it.

Deploying the Mock

Since we chose AWS Elastic Beanstalk for hosting, we first of all need an AWS Account. In our account we will create an IAM user which we can then use to create our Elastic Beanstalk environment.

Set up your Account

If you do not have an AWS Account yet, create one. The process is pretty straightforward and well explained. After creating your account, you will have root access to it. Even though you could use your root account to complete all of our following steps, it is best practice to create an IAM user which only has the permissions necessary to do so.

Create a suitable IAM User

To create an IAM user, log in to the AWS console using your root account and select IAM from the list of services. In the “Users” tab, you can choose to create a new user. Supply a username and make sure to at least tick the box for “Programmatic Access”. When asked to assign permissions, choose “Attach existing policies directly” and select “AWSElasticBeanstalkFullAccess” from the list. In the last step of the process, make sure to save both the
Access Key ID and the Secret Access Key, since you will not be able to access the secret key later.

Set up your Beanstalk Application

Before starting this step, you need to have the AWS Elastic Beanstalk CLI installed on your machine. You can find the installation instructions here.

After installing the EB CLI, initialize your Beanstalk application by running the following command from within your user-mock directory:

eb init

This will ask you for a couple of things:

1. A region to host your application in
   → Up to you. I went with “eu-central-1”
2. Your AWS Access Key ID + Secret Access Key
   → Use the values you got when creating your IAM user
3. Use an existing application or create a new one
   → We want to create a new one
4. Enter an application name
   → Enter whatever you want the name to be
5. Confirm that you are using Node.js or to select a platform
   → In case you have to select a platform, choose Node.js
6. If you want to use CodeCommit
   → For this tutorial, AWS CodeCommit is not needed

Create your Beanstalk environment

In our next step, we will create an Elastic Beanstalk environment and upload the first version of our mock by running: (this can take a few moments)

eb create dev-mock-env

Note: If you run into any permission errors in this step, make sure you are using the latest version of the EB CLI.

If you did not get any errors, your application should now be running and you can access it by running:

# Open your application in your default browser
eb open

This should open the mock application in your default browser. As earlier, adding /docs to the URL brings you to Swagger UI. Adding /api/v1/user/0 to the URL will return the dummy user from UserService.js.

In case you run into any errors or see error pages, viewing the logs of your application might be helpful. You can view them using the AWS console in your browser or by simply running

# Get the most recent logs right into your terminal
eb logs
# Open your application in the AWS Elastic Beanstalk Console
eb console

That’s it. You’ve managed to create a mock backend and host it within approximately 15 minutes. Wasn’t that easy?

Last but not least, let me show you how you can clean up all the resources you’ve created during this walkthrough:

# Terminate and clean up the environment
eb terminate dev-mock-env