Throughout web and mobile software, you’ll find APIs to exchange data. They are now a foundational element of the development process. Many organizations have adopted an API-first approach, where this interface that programmers see is built before one that users see.

The most forward-thinking companies will prototype their API designs before committing them to permanent code. While this can happen with any language, Python is easy to read and has straightforward frameworks to help build REST APIs. In this tutorial, we’ll look at two Python API frameworks, as well as a code-free way to create mock servers.

Before diving into Python examples, it’s important to understand the overall API design process. Your goal is to quickly create an interface. You want our API consumers (such as a frontend web team) to envision what’s possible, even before live data is flowing through the code. You’ll get early feedback that could lead to important updates to your API that could have been major changes if you waited until the API was “complete.”

This design-first API process is covered in the API Design Guide, which says design-second APIs are an oxymoron. In other words, anyone creating an API is designing one. Unfortunately, in code-first APIs, the design is a guess that gets harder to change.

Keep in mind, even as you stub out the endpoints in this tutorial, we’ll be using mock data. It’s meant as a representation of your API-in-progress. It’s up to you whether you iterate upon it for your eventual production API.

Most REST APIs use resource endpoints and HTTP methods to help communicate actions. In this first example, let’s create a /companies endpoint and perform a simple GET request to retrieve a list of companies.

The code includes a hard-coded array of two company objects to use as results. Next, we initialize Flask and declare a route for our endpoint. When a consumer visits /companies using a GET request, the list of two companies will be returned.

Save the code as flaskapi.py and then run it from the command line: python flaskapi.py. Follow the local URL provided, and tack on our endpoint, such as http://localhost:5000/companies

There’s a bit more to the boilerplate for Falcon. It uses a class for each resource and connects routes to instances of a resource. Due to the use of a class, it makes more sense to declare the hard-coded array of companies within the company resource class. The result is the same as our previous example, returning the JSON version of the company list.

This will look for a POST to /companies with company data in the body of the request. Rather than handling the data (since this is just mocking the endpoints), we return success and include a 201 status code. In the GET example a status code wasn’t required because 200 is Flask’s default.

You can copy existing routes to add other endpoints. Edit the path and method to match your requirements. Flask does not restrict how you declare your endpoints, but you’ll find it easier if you keep them logically grouped.

To handle a POST, we define an on_post function. As with our Flask example, we’ll simply return success, along with a 201 status code. Falcon also assumes a 200 and has helper constants for common statuses.

Both Flask and Falcon provide fast ways to prototype a REST API in Python. If you are practicing design-first APIs, you can create mock servers before you write any code. All you’ll need is an OpenAPI document of your new API. For design-first organizations, these machine-readable descriptions serve as a source of truth for what’s possible with an API.

You can use an open source command line utility like Prism API Server to stage a mock API. It will consume your OpenAPI document to determine the endpoints, methods, and data supported by the API. Then it serves mock data and validates the API description.

Stoplight also provides hosted mock API servers which connects Prism to your API design and testing process. It’s easy to make sample calls against your mock API right from the browser. Then you can share them with your team and even connect your server to the frontend before you write any backend code.

No matter how you create your REST API, whether through code or generated from an OpenAPI document, collaboration is important. Mock APIs help you get feedback early. You can learn more in our Mock API Server Guide.

Read how world’s leading API first companies are solving API Design Management at Scale.