Skip to content

Latest commit

 

History

History
174 lines (125 loc) · 5.7 KB

01-environment-and-boilerplate.md

File metadata and controls

174 lines (125 loc) · 5.7 KB

01 - Set up the environment and create your first project

Code for this chapter available here.

In this section we will create a basic environment to develop our API using Docker, initialize a requirements.txt and generate some basic layout using apistar commands.

Prequisites: You need a working Python3 installation for this introduction; but if you don't have one, don't worry! We will use Docker to containeraize our environment. You can also use a docker python image to use pip.

Install apistar and create a layout project

Pip is a tool to install Python packages. Using it, install the API Star framework.

$ pip3 install apistar

The package also provides a command line tool that can create a basic layout for a new API Star project. It also generates an example welcome view and routing for the documentation and static files.

$ mkdir api/
$ apistar new api --layout minimal

You can also run the app via the apistar shell tool, and view the API interactive documentation in localhost:8000/docs/.

$ cd api/
$ apistar run

Create a requirements.txt file to define the project dependencies. We will use pip freeze to pin the specific version of the packages.

$ pip3 freeze | grep apistar > requirements.txt
$ cat requirements.txt
  apistar==0.1.17

Set up an environment using Docker

Docker is a really good way to pack and ship your applications; offering a good tooling ecosystem for a devops environment, from the first commit in your dev environment to the wild.

TODO Install docker and docker-compose using the official documentation, and then come back.

We will define a simple docker image to add the requirements.txt and install the dependencies via the following Dockerfile.

FROM python:3.6

WORKDIR /app/
COPY requirements.txt /app/

RUN pip3 install -U pip \
    && pip3 install -r requirements.txt

ADD ./api/ /app/

Build the image. The parent image python:3.6 default command is python3, so running it without additional parameters will provide an interactive python shell (with the dependencies installed; try import apistar):

$ docker build -t basepython .
$ docker run --rm -it basepython
 Python 3.6.1 (default, Jun  8 2017, 21:43:55) 
 [GCC 4.9.2] on linux
 Type "help", "copyright", "credits" or "license" for more information.
 >>>

Just a reminder about the docker run parameters. Here we will execute an interactive shell. Given that we are running an ephimeral container, we pass rm parameter to remove it after you exit the shell and the container stops. it (interactive, tty) are used here to interact via stdin with the process in a terminal; as the man docker run specifies -t [...] can be used, for example, to run a throwaway interactive shell.

Finally we can execute apistar in our python docker image! Let's see its usage:

$ docker run --rm basepython apistar
 Usage: apistar [OPTIONS] COMMAND [ARGS]...
 
   API Star
 
 Options:
   --version  Display the `apistar` version number.
   --help     Show this message and exit.
 
 Commands:
   new     Create a new project in TARGET_DIR.
   run     Run the current app.
   schema  Output an API Schema.
   test    Run the test suite.

new generates a new project in the directory passed as parameter, creating an example welcome endpoint and basic project structure.

$ mkdir api
$ docker run --rm -v `pwd`/api:/app basepython \
    apistar new . --layout standard

  ./app.py
  ./tests/test_app.py
  ./tests/__pycache__/test_app.cpython-36.pyc
  ./__pycache__/app.cpython-36.pyc
  ./project/routes.py
  ./project/__init__.py
  ./project/views.py
  ./project/__pycache__/routes.cpython-36.pyc
  ./project/__pycache__/views.cpython-36.pyc
  ./project/__pycache__/__init__.cpython-36.pyc

-v is mounts the host api directory recently created to the container /app container, the working directory defined in the Dockerfile, as a volume.

Explore the sample code, run the project and enjoy the autogenerated documentation.

$ docker run \
    --rm -v `pwd`/api:/app \
    -p 8080:8080 \
    basepython \
    apistar run --host 0.0.0.0

  Starting up...
   * Running on http://0.0.0.0:8080/ (Press CTRL+C to quit)
   * Restarting with stat
   * Debugger is active!
   * Debugger PIN: 957-476-005

$ http localhost:8080

  HTTP/1.0 200 OK
  Content-Length: 35
  Content-Type: application/json
  Date: Fri, 16 Jun 2017 23:10:14 GMT
  Server: Werkzeug/0.12.2 Python/3.6.1
  
  {
      "message": "Welcome to API Star!"
  }

I will be using httpie client to interact with the API. Don't forget to get a glance of the autogenerated API doc and try the interactive client at http://localhost:8080/docs/.

Congrats, your first API Star project is up and running ;-)

Appendix: A docker-compose.yml project definition

We will use a docker compose yaml file to specify our base service and to avoid passing at every run the same parameters. It allows to define the diferent services of our environment (i.e. a database) and to orchestate them.

version: '2'

services:
  pythonbase:
    build: .

  api:
    extends: pythonbase
    entrypoint: apistar
    command: ["run", "--host", "0.0.0.0", "--port", "80"]
    working_dir: /app
    volumes:
      - "./api:/app"

Now you can run the project using docker-compose instead of a docker command with multiple parameters. This will become handy when we add more complexity to the stack:

$ docker-compose run -d api

Next section: 02 - A basic CRUD API with TDD

Back to the table of contents.