Rapid API Prototyping

The goal of my Rapid API project is to create a containerized starting point that can be used to quickly implement a prototype of an API, customize it as needed, and easily add initial content.

Preparation

To get started, create a new GitHub repository, initialized it with a README and a license, and clone it to your local machine.

Docker files

Add a docker-compose.yaml file with the following content:

version: '3.7'
services:
  rapid-api:
    container_name: api-dev
    build: ./docker/sqlite
    ports:
      - '8080:8080'

This file points to a Dockerfile in the /docker/sqlite folder and maps container port 8080 to host port 8080 so we can access our API.

Next, add a docker folder with a sqlite sub folder. There, create a Dockerfile with the following content:

FROM node:13.14.0-alpine3.11

RUN apk update && apk upgrade 
RUN yarn global add strapi

WORKDIR /app

RUN strapi new . --quickstart --no-run 
RUN yarn install --force
RUN strapi install documentation && strapi install graphql

RUN sed -i 's/1337/8080/g' ./config/server.js

COPY settings.json /app/extensions/documentation/config/
COPY entrypoint.sh /usr/local/bin/

RUN chmod 755 "/usr/local/bin/entrypoint.sh"

EXPOSE 8080

ENTRYPOINT ["/usr/local/bin/entrypoint.sh"]

As you can see, the Dockerfile uses the latest Node JS 13 version. At the time of writing, Node JS 14 has already been released, but not all of strapi’s dependencies were available at the time of writing.

The docker build starts with installing the strapi CLI, which it then uses to create a new quickstart project. This initializes a strapi project using a SQLite database. It then installs the API documentation and GraphQL plugins and changes the default port number from 1337 to 8080. In addition, it copies a settings.json file and an entrypoint.sh file to the image.

Open API settings

Next to the Dockerfile in the sqlite folder, add a settings.json file with the following content:

{
    "openapi": "3.0.0",
    "info": {
      "version": "1.0.0",
      "title": "DOCUMENTATION",
      "description": "",
      "termsOfService": "YOUR_TERMS_OF_SERVICE_URL",
      "contact": {
        "name": "TEAM",
        "email": "contact-email@something.io",
        "url": "mywebsite.io"
      },
      "license": {
        "name": "Apache 2.0",
        "url": "https://www.apache.org/licenses/LICENSE-2.0.html"
      }
    },
    "x-strapi-config": {
      "path": "/documentation",
      "showGeneratedFiles": true,
      "pluginsForWhichToGenerateDoc": [
        "email",
        "upload",
        "users-permissions"
      ]
    },
    "servers": [
      {
        "url": "http://localhost:8080",
        "description": "Development server"
      },
      {
        "url": "YOUR_STAGING_SERVER",
        "description": "Staging server"
      },
      {
        "url": "YOUR_PRODUCTION_SERVER",
        "description": "Production server"
      }
    ],
    "externalDocs": {
      "description": "Find out more",
      "url": "https://strapi.io/documentation/"
    },
    "security": [
      {
        "bearerAuth": []
      }
    ],
    "paths": {},
    "tags": [],
    "components": {}
}

This file is needed in order to correct the port number used by the Open API endpoint. Feel free to edit the other settings to your liking. For more info, see this section in the strapi documentation.

Entrypoint

Next to the Dockerfile in the sqlite folder, add an entrypoint.sh file with the following content:

#!/bin/sh

# exit when any command fails
set -e

echo "Starting Server"

strapi develop

This entrypoint script simply starts the strapi project in development mode, with automatic reload enabled.

First run

Startup the container for the first time:

docker-compose up --build

It will take a while before we are ready for the next steps. The base image is downloaded, updates are installed, the strapi project is initialized and the Documentation and GraphQL plugins are installed. Once this is completed, the container is started and some log entries appear. Eventually you will see something like this, indicating that the container is successfully started:

api-dev      | One more thing...
api-dev      | Create your first administrator 💻 by going to the administration panel at:
api-dev      |
api-dev      | ┌──────────────────┐
api-dev      | │ http://localhost:8080/admin  │
api-dev      | └──────────────────┘
api-dev      |

You are now read to navigate to http://localhost:8080/admin, create an admin account and start customizing your API.

Adding Content

Let’s add a first example resource together.

From the menu on the left, select the Content-Types Builder and choose Create new collection type. Give it a display name Example and continue. Now we can add our choice of fields to our collection type: As you can see, strapi comes with a nice set of built-in field types. Feel free to experiment with them. For now, we will just add a Text field called Name and a Rich Text field called Description. Hit Finish and then Save. Strapi will now generate the Example API and restart the server. Once complete, you will see the Example collection type appear in the top left. Open it up and add a few examples.

Checkout the strapi documentation and tutorials for more examples.

Test the API

Now that we have added some content and created our first API, we want to see it in action. You can use the API client of your choice to test it (postman, insomnia, curl, etc,) At the moment, I prefer to use Visual Studio Code with the REST Client plugin. Add a test.http file with the first test:

###
GET http://localhost:8080/examples

A little Send Request label will appear, and when you click that, Visual Studio Code will execute the GET request. You will get a response like this:

HTTP/1.1 403 Forbidden
...
Connection: close

{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "Forbidden"
}

Your API supports authentication and is not open to the public! For the sake of this test, in your strapi Admin UI, navigate to Roles & Responsibilities, select Public and check Select All next to Example and save that.

Now try sending the request again, you should receive the examples that you’ve added previously.

For our last exercise, let’s use the API to add another entry. Add the following to the test.http file:

###
POST http://localhost:8080/examples
content-type: application/json

{
  "name": "API Example",
  "description": "Added using the API"
}

Don’t forget the content-type header! Strapi will check for this and create an entry with empty values if you forget to specify that!

API Documentation

You will find another nice feature of our setup when you navigate to Documentation. Click in the Retrieve your jwt token textbox and the token will be copied to the clipboard. Click on Open the documentation and the Swagger based OpenAPI endpoint will be opened. You can Authorize yourself with your token and get familiar with all the options that your API has to offer.

GraphQL

A main reason for me to try strapi for rapid API prototyping is its support for GraphQL. I am not yet very familiar with GraphQL and want to have a playground to learn more.

Your API’s GraphQL Playground is available at http://localhost:8080/graphql. See this section in the strapi documentation for more info.

Even easier…

Don’t want to go through the effort described above? I’ll do you one better. The resulting container image is available here on docker hub, so you can get started with a single line:

docker run -p 8080:8080 akleinloog/rapid-api

The code

If you want to see how to set up a prototype using MongoDB instead of SQLite, or wonder how I built and published the container image to docker hub, feel free to check out the repository on Github.