simple-tracker-spec

An OpenAPI Spec and Postman Collection for APIs that are part of the "Simple Tracker" project.

Is there a language you just wanna tinker with? Give us an API or a Front End, just be sure to use the OpenAPI spec here to create your API.

Example API here

Example Front End here

The idea here is that we need some sort of app that can be used in many contexts. Why one specific app? Because then we can easily recycle content. Why a bunch of languages? Because then we can tailor the demos, workshops, PoCs we do to match the audience's ecosystem.

Every single API and Front End should have the following accompaniments:

• Dockerfile
• devcontainer (for Codespaces, useable in vscode with Remote Containers)
• Actions workflow for building an image and storing it in GitHub Container Registry (ideally using a reusable workflow)
• GHAS enabled
  • Dependabot
  • Secret Scanning
  • Code Scanning

The APIs should all additionally:

• Include an Action workflow that can run a smoke test verifying the API conforms to the API Spec

Postman collections can be run in GitHub Actions using the newman collection runner.

newman run -e Local.postman_environment.json api-test-collection.json

The simple-tracker-api.postman_collection.json was generated from the api spec. It is here as a reference.

To run the collections during local development without needing to grab the collection and environment files, do the following:

npm install -g newman
curl https://api.github.com/repos/boxboat-github-practice/simple-tracker-spec/contents/smoketest.sh \
  | jq -r .content | base64 -d > smoketest.sh

chmod +x smoketest.sh

# seed the db with some data
smoketest.sh seed

# test types are one of [employees, clients, contracts, history]
smoketest.sh employees

...

┌─────────────────────────┬─────────────────┬─────────────────┐
│                         │        executed │          failed │
├─────────────────────────┼─────────────────┼─────────────────┤
│              iterations │               1 │               0 │
├─────────────────────────┼─────────────────┼─────────────────┤
│                requests │              13 │               0 │
├─────────────────────────┼─────────────────┼─────────────────┤
│            test-scripts │              13 │               0 │
├─────────────────────────┼─────────────────┼─────────────────┤
│      prerequest-scripts │               0 │               0 │
├─────────────────────────┼─────────────────┼─────────────────┤
│              assertions │              24 │              17 │
├─────────────────────────┴─────────────────┴─────────────────┤
│ total run duration: 328ms                                   │
├─────────────────────────────────────────────────────────────┤
│ total data received: 3.51kB (approx)                        │
├─────────────────────────────────────────────────────────────┤
│ average response time: 7ms [min: 3ms, max: 36ms, s.d.: 8ms] │
└─────────────────────────────────────────────────────────────┘

To Do:

• create reusable workflows for building containers
• write tests for the Postman Collection
• create reusable workflow for smoke tests
• creat reusable workflow for deploying to a long-living tools cluster
• create helm chart for deploying a full microservice instance, allowing for hot swappabble units
• create the kube magic to make hot swapping possible, configmaps, secrets, etc
• architecture designs and IaC for AWS, Azure and others if you really want to

Let's start simple and keep that way as long as possible.