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

  • JSON/YAML editing
  • Swagger Open API specification
  • Some basic knowledge of Python development

Step 1: Document your API

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

Step 2: Generate a Flask API

Create your virtual environment with Miniconda and install requirements

  1. Open your Terminal
  2. Create your virtual environment with conda
  3. Activate your virtual environment
source activate <yourenvname>

4. Install the codegen library Swagger-py-Codegen

pip install swagger-py-codegen

Generate the API

  1. 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 ‘Failure with: TypeError: descriptor ‘capitalize’ requires a ‘str’ object but received a ‘unicode’, consider installing the Issue-100 branch 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. Open the host URL returned in your terminal, most likely it will be:
http://127.0.0.1:5000 

3. With an application like POSTMAN or Chrome App Advanced REST client 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

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. Create a new repository on Github for your API.
  2. Start a Bash console in your Python Anywhere account and add your Github repository as a remote.
  3. Still in Python Anywhere set up your virtual environment, 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 www.mariacerase.com

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