A detailed guide for Product Managers to prototype APIs

Prototyping and testing are among the most important, yet most ignored phases of the product development cycle. This is especially true when less experienced product managers work on non graphical interfaces, as it is easier to think of visual prototypes than it is of APIs.

Here is a complete guide for product managers, to produce a simple API prototype that can be used for user testing and as a precious artefact to express requirements to the development team. Let’s start!

Skills Required

  • Browse files via Terminal
  • JSON/YAML editing
  • Swagger Open API specification
  • Some basic knowledge of Python development

Step 1: Document your API

Head towards the web editor and create your API docs with YAML or JSON, respecting the . You can start off with the example doc of the Petstore, and work your changes from this skeleton API towards your desired behaviour. Make sure to always add examples to the properties of your definitions, and to describe error responses.

Once the doc is ready and valid select File > Download JSON.

Step 2: Generate a Flask API

is a lightweight Python micro-framework that allows you to create microsites and applications quite easily. The following steps are for Ubuntu, for other operating systems, check out how to set up your and .

Create your virtual environment with Miniconda and install requirements

  1. Download and install for Python 2.7
  2. Open your Terminal
  3. Create your virtual with conda
  4. Activate your virtual environment
source activate <yourenvname>

4. Install the codegen library

pip install swagger-py-codegen

Generate the API

  1. Navigate to the folder where you saved your API.json specification and follow the instructions from to generate a Flask API.
  2. You may run into problems with the library, especially from the parser: the library unlike Swagger 2.0 does not support circular references and may have glitches when working with unicode JSON. You can overcome these problems by removing circular references from the JSON and if you get , consider installing the in your environment with:

To install a python package from a local folder, where you saved the Issue-100 branch, you can:

pip install /pathtopackage

Test the API locally

  1. With your virtual environment still active, navigate to the first subfolder of the generated api and run __init__.py as per .
  2. Open the host URL returned in your terminal, most likely it will be:
 

3. With an application like or you can now perform calls to this local server and check out responses, the same way you specified in your doc.

Add more data to your prototype

There is only so much that the prototyping can do: there is no specific business logic defined and also objects returned are very simple. You can add some more depth to your mock responses with additional data.

In the ‘Users.py’ file for example, you can return an array of two mock users, rather than an array of 1 user.

Once you are happy with your prototype on your local machine, you are ready to deploy it and share it with the rest of the world.

Step 3: Deploy on Python Anywhere

  1. Signup to for a free account.
  2. on Github for your API.
  3. Start a Bash console in your Python Anywhere account and .
  4. Still in Python Anywhere set up , activate it and navigate to where you uploaded your requirements.txt file (available in your Flask API folder). Then run a standard:
pip install -r requirements.txt

5. Now you can pull your api files from Github. Run:

git pull origin master

All the files of your repository should now have been imported in your Python Anywhere file folders.

6. To make Python Anywhere correctly locate the file to execute, you will have to edit the WSGY file that you can reach from the ‘WEB’ tab. In particular you may need to change this file to look like this:

Change the __init__.py file under /<account_name>/<first_folder>/<second_folder> as follows

7. Go to the ‘WEB’ tab and Reload your application.

The API is now available on https://<account_name.pythonanywhere.com> for you and anyone else to test.

Eternal searcher, sample of Italian madness. Product and Usability expert. Find more about me on

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store