A simple echo API to demonstrate that API spec's are for more than just documentation.
Switch branches/tags
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
echo
sdk/python
static
README.md
api.py
client.py
dredd.yml
echo-example.postman_collection.json
openapi.yml
requirements.txt
zappa_settings.json

README.md

Echo API Example

This is a simple API to echo back a string. It's primary purpose is to demonstrate that API spec's are for more than just documentation.

In this example, an OpenAPI spec is used for

  • Mocking an API as a prototype
  • Testing an API implementation against the spec
  • Generating Postman collections for deeper testing
  • Eventually, generating documentation

Mocking a new API

First, for the purposes of rapid prototyping, craft an API spec using tools like SwaggerHub.

Here's a spec I created earlier that allows you to do some mock API calls.

Implementing that API

Start coding against the API spec to implement various features. This API is quite simple, just an /echo endpoint.

Code Generation

You can use a variety of tools to generate code from your API spec.

pip install swagger_py_codegen
swagger_py_codegen -s openapi.yml . -p echo

To make this work for the spec I've then gone and modified the /v1 prefix in the blueprint, and the echo/v1/api/echo.py file to implement ?echo.

I personally, however, am not a fan of code-gen and code magic in general. So, for such a simple API I prefer to setup and implement this myself.

Implementation

If implementing this yourself then you want to setup the repo (or just clone this one) and then go ahead and install the dependencies.

Setup

git clone https://github.com/devjack/echo-api-example.git && cd echo-api-example

# A simple virtual env for this project
python -m venv ../echo-api-example.env
. ../echo-api-example.env/bin/activate

Dependencies

Simplest - use requirements.txt

pip install -r requirements.txt

If you prefer, you can install the three dependencies directly.

pip install zappa flask

Test against the spec

We'll use dredd to do this.

npm install -g dredd
dredd init
dredd

Extra tests (Postman)

You can import an OpenAPI spec to postman. But, I've already done that for you in echo-example.postman_collection.json. You can then write tests against API calls. For more reading I'd highly recommend reading this excellent collection of tips for API testing.

Since we already have a postman collection in the repo:

npm install -g newman
newman run echo-example.postman_collection.json

Deployment

From scratch, you can run zappa init to setup a serverless deployment.

I've already generated (and further configured for TLS and a custom domain etc) so deployments are run by:

# First time
zappa deploy

# subsequent times
zappa update production

See zappa_settings.json for an example.