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 Swagger web editor and create your API docs with YAML or JSON, respecting the Open API spec. 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

Flask 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 Virtualenv for Windows and Mac OS.

Create your virtual environment with Miniconda and install requirements

1. Download and install Miniconda for Python 2.7
2. Open your Terminal
3. Create your virtual environment with conda
4. Activate your virtual environment

source activate <yourenvname>

4. Install the codegen library Swagger-py-Codegen

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 guokr 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 ‘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. With your virtual environment still active, navigate to the first subfolder of the generated api and run __init__.py as per instructions.
2. 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

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 Python Anywhere for a free account.
2. Create a new repository on Github for your API.
3. Start a Bash console in your Python Anywhere account and add your Github repository as a remote.
4. 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.