Starting a new software project is like going on a road trip with friends to a new destination. Before hitting the road, you’d need a map to guide you. In software development, an API definition acts like that map. It’s a blueprint that tells developers how different parts of an application should communicate. For software developers, understanding this concept is key to building scalable applications.

In this guide, we’ll explain how to turn an API definition into a working backend, the “engine” that controls apps behind the scenes.

What is an API definition?

An API definition is a blueprint that describes how an API works. It outlines the available endpoints, the types of requests you can make (e.g., retrieving, submitting, or updating data), and what kind of responses to expect. It also specifies how the data is structured—typically in formats like JSON or XML.

For example, if you’re building a weather app, the API definition might tell you how to request the current temperature for a specific city. It’s like having a set of instructions for using the API.

There are different formats for writing an API definition, such as OpenAPI (formerly Swagger), RAML, and API Blueprint. These formats help developers create consistent and easy-to-understand APIs.

Why generate a backend from an API definition?

1. Saves Time: Instead of writing all the code from scratch, you can automate some manual coding tasks.
2. Reduces Errors: When you use a tool to generate code, it’s less likely to make mistakes than manual coding.
3. Consistency: Your backend will follow the same structure as your API, making it easier to maintain and scale.

Approaches for automation

Once you have your API definition, you’ll want to convert it into working code. Then, you can customize the code to meet your specific needs. 

‍

There are some tools available that assist in automating the process of creating backend applications from API definitions. In my workflow, I use Blackbird that allows me to generate boilerplate code from your OpenAPI spec in just a few clicks. This jumpstarts development by handling the repetitive scaffolding work, so I can focus on building the logic and features that matter most.

Also, it supports a spec-first workflow that integrates directly with your development process, helping streamline everything from initial code generation to ongoing iteration.

Preparing the API definition

Before you can generate a backend, you need a well-written API definition. Here’s how to prepare one:

Choosing an API Specification Format

There are several formats you can use to write your API definition:

1. OpenAPI 

OpenAPI is the most widely-used format for RESTful APIs. It’s written in YAML or JSON and is very detailed.

2. RAML 

RAML is another popular format for RESTful APIs that are designed to be human-readable.

3. API Blueprint

API Blueprint is a more straightforward format often used for smaller projects.

4. GraphQL

GraphQL is a query language for APIs. Instead of endpoints, you define a schema for queries and mutations.

5. SOAP 

SOAP (Simple Object Access Protocol) is an older format that uses XML. It’s more complex but still used in some systems.

6. Postman Collection 

Postman created their own API format based on JSON that is used for testing but can also define APIs.

7. Plain Text

Sometimes, APIs are defined informally in plain text. This is not structured but can be helpful for quick documentation.

Writing or Obtaining an API Definition

If you’re creating a new API, you’ll need to write the API definition yourself after selecting a format you are comfortable with. Tools like Blackbird can help you write it in a structured way.

If you’re using an existing API, you can often download the API definition from the provider’s website. For example, many public APIs like Twitter or Google Maps provide API definitions in OpenAPI format.

Let’s say we’re building a simple API for a to-do list aApp. Our API will allow users to:

1. Get a list of all to-do items.
2. Add a new to-do item.
3. Update an existing to-do item.
4. Delete a to-do item.

Here’s how we can write the API definition in OpenAPI format (YAML):

This process can be easily simplified using a tool like Blackbird. Blackbird is an API development platform that lets you import specs, design, test, deploy, and manage powerful APIs quickly and precisely. Blackbird streamlines the entire API lifecycle from mocking and documentation to debugging and deploying. Now let's use Blackbird for this process.

‍Step 1: Create an account on the Blackbird platform

Step 2: Go to the API section and click on Add API. On the pop-up, click to scan your repo for specs or create an API. Using the chat interface, tell the system what you would like to create.

When the system is done generating, you can accept or continue to make modifications as necessary.

‍Step 3:Create the API

Step 4: Download the OpenAPI definition in JSON

Generating Boilerplate Code for the Backend

Once you have your API definition, boilerplate code can be generated. Boilerplate code is the basic structure of your backend, including things like:

• Routes (the paths your API will use).
• Models (the structure of your data, like a user’s name and email).
• Controllers (the logic that handles requests and responses).

You can generate this code using an open-source tool like OpenAPI Generator, or access this feature in Blackbird. For example, if you’re using Node.js, the tool will create files like app.js, routes.js, and models.js for you.

First, we’ll look at how to use the OpenAPI Generator tool for this.

Step 1: Install OpenAPI Generator

You’ll need to install OpenAPI Generator. If you’re using Node.js, you can install it globally with npm:

Step 2: Generate the Boilerplate Code

Once installed, you can use the following command to generate the boilerplate code:

‍

• -i todo-api.yaml: Specifies the input file (our API definition).
• -g nodejs-express-server: Specifies the generator to use (in this case, a Node.js Express server).
• -o ./todo-backend: Specifies the output directory where the code will be generated.

Step 3: Explore the Generated Code

After running the command, you’ll find a new folder called todo-backend with the following structure:

Let’s break down what each file and folder does:

Configuration Files

• .eslintrc.json: Configuration file for ESLint, a tool that helps enforce coding standards.
• .openapi-generator-ignore: Specifies files or folders that should not be overwritten when regenerating code.
• README.md: This is an essential guide to help you get started with the generated code.
• config.js: This file contains configuration settings for your application, such as the server port or database connection details.

API Definition

• api/openapi.yaml: A copy of your API definition file. The server uses this to validate requests and responses.

Controllers

• controllers/Controller.js: A base controller class that other controllers can extend.
• controllers/DefaultController.js: A default controller that handles basic requests. You’ll replace this with your controllers.
• controllers/index.js: Exports all the controllers so they can be easily imported elsewhere.

Services

• services/DefaultService.js: A default service that contains basic logic. You’ll replace this with your services.
• services/Service.js: A base service class that other services can extend.
• services/index.js: Exports all the services so they can be easily imported elsewhere.

Server Setup

• expressServer.js: Sets up the Express server, including middleware and routes.
• index.js: The entry point for your application. It starts the server and loads the necessary modules.

Utilities

• logger.js: A utility for logging messages to the console or a file.
• utils/openapiRouter.js: Handles routing based on the API definition.

Generating Boilerplate Code for the Backend Using Blackbird CLI

Another approach to this would be using the Blackbird CLI to generate our code easily.

Step 1: Download the Blackbird CLI

Follow here to install the CLI

Step 2: Run the CLI 

Let’s run the CLI and have it generate our code for us easily

What each part means:

• blackbird code generate server: Tells Blackbird to generate server-side code.
  
• nodejs-express-server: Chooses Node.js with Express as the framework.
  
• -s To-Do.json: Uses the To-Do App API.json file as the API specification.
  
• -o ~/Desktop/Test2/todo: Outputs the generated code into your ~/todo/ directory.

With Blackbird CLI, we have been able to quickly generate our backend code via a simple process.

Implementing Business Logic

After generating the boilerplate code, you must add your business logic. This is the part of the code that makes your app unique. For example:

• If you’re building a weather app, your business logic might include fetching data from a weather API.
• If you’re building a social media app, your business logic might include creating posts or following users.

Since we’ve generated the boilerplate code for our To-Do List App, it’s time to add the business logic. This is where we make our app unique by defining how it works. For our to-do app, the business logic will include:

• Fetching a list of to-do items.
• Adding a new to-do item.
• Updating an existing to-do item.
• Deleting a to-do item.

Connecting to a Database or External Services

Most backends need a place to store data. For our to-do app, we’ll use a database to store the to-do items. Let’s connect our backend to a popular NoSQL database, MongoDB.

‍

Step 1: Install MongoDB and Mongoose

First, install MongoDB on your machine or use a cloud service like MongoDB Atlas. Then, install the mongoose library to interact with MongoDB:

Step 2: Set Up the Database Connection

In the config.js file, add the MongoDB connection details:

Then, create a new file called db.js in the utils folder to handle the database connection:

Finally, update the index.js file to connect to the database when the server starts:

Writing Controllers, Services, and Middleware

Step 1: Define the To-Do Model

Create a new file called Todo.js in the models folder to define the structure of a to-do item:

Step 2: Update the Services

Open the services/DefaultService.js file and add methods to interact with the database:

Step 3: Update the Controllers

Open the controllers/DefaultController.js file and add methods to handle requests:

Step 4: Add Middleware

Middleware is code that runs before or after a request. You can add middleware to log requests or validate data.

Create a new file called logger.js in the middleware folder:

Then, update the expressServer.js file to use the middleware:

Ensuring API Security and Authentication

Security is critical for any API. Here are some steps to secure our to-do app:

Step 1: Add Authentication

A library like JSON Web Tokens (JWT) can authenticate users. Install the necessary packages:

Create a new file called auth.js in the middleware folder to handle authentication:

Step 2: Add Rate Limiting

Use the express-rate-limit library to prevent abuse of your API:

Update the expressServer.js file to add rate limiting:

Running and Testing the Generated Backend

Once your backend is ready, you must test it to ensure its functionality. You should write automated tests to catch any bugs. For example, you can test your code using a framework like Jest (for JavaScript) or Pytest (for Python) that integrates with whatever tool you’re using and your IDE.

Now, let's test our code using Swagger UI to send requests to our API and inspect the responses.

Example: Testing the To-Do API

• GET /todos: Fetch all to-do items.
• POST /todos: Add a new to-do item.
• PUT /todos/:id: Updates a to-do item.

DELETE /todos/:id: Delete a to-do item.

Enhancing and Customizing the Backend

After testing, you should add more features or improve the performance of your backend. For example:

• Caching can make your API faster by storing frequently accessed data in memory. 
• A load balancer can be used to handle more traffic.
• Adding logging will help to track errors and usage.

Deploying the Generated Backend

Finally, you’ll need to deploy your backend so others can use it. If you’re not using a tool like Blackbird that comes with access to a hosted environment, you can deploy to a cloud platform like AWS, Google Cloud, or Heroku. After deployment, monitor your API to catch any issues.

1. Choose a Platform

• Blackbird: Built-in hosted environment. No setup.
• Heroku: This is easy for beginners; a free tier is available.
• AWS: Scalable, great for large apps.
• Google Cloud: It integrates well with Google services.
• Render: Simple and fast; free tier available.

2. Prepare Your App

• Use environment variables for sensitive data (e.g., database credentials).
• Switch to a cloud database like MongoDB Atlas or AWS RDS.
• Ensure all dependencies are in package.json.

3. Monitor Your App

• Use tools like New Relic or Datadog to track performance and errors.
• Set up alerts for downtime or high traffic.

Let’s deploy our To Do app backend on Render.

1. Prepare the App for Deployment

Add a Start Script
In package.json, add:

"scripts": {
"start": "node server.js"
}

2. Push Your Code to GitHub

Step 1: Initialize a Git Repository

If you haven’t already, run:

Step 3: Create a GitHub Repository

• Go to GitHub and create a new repository.
• Follow the instructions to link your local code to GitHub:

4. Deploy to Render

1. Connect Your GitHub Repo to Render

1. To sign in to Render, go to the Render Dashboard and log in (you can sign up on GitHub if you haven’t already).
2. Create a Web Service:
   
   • Click New + → Web Service.
   • Under GitHub, click Connect account (if not already connected).
   • Select your To-Do app repository from the list.

2. Fill in Deployment Details

Configure your app’s settings in Render:

Basic Settings

• Name: Give your app a name (e.g., todo-app).
• Region: Choose the closest region (e.g., "Oregon" for the US).
• Branch: Select the branch to deploy (e.g., main).

4. Deploy!

• Click Create Web Service.
• Render will:
  
  1. Pull your code from GitHub.
  2. Install dependencies (npm install).
  3. Start your app using npm start.

5. Test Your Live API

Conclusion

Generating a backend from an API definition is the fastest and most error-free way to develop. There are tools like Blackbird that can create and mock specs instantly, build a basic backend in a matter of minutes, and customize elements to your needs. Knowing API definitions and how to use them is valuable for building a simple app or a complex system. Now that you’ve seen how easy it is, why not try it on your next project?

‍