A detailed guide for Product Managers to prototype APIs

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.

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>
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:
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 

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.

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
git pull origin master

--

--

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

Love podcasts or audiobooks? Learn on the go with our new app.

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
Maria Cerase

Maria Cerase

122 Followers

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