stackbreak / tasx

Example microservice app built with Go

Tasx

Tasx is an example microservice app built with Go.

About

This app provides REST API for the creation and management of the task lists linked to users.

For user access separation is used JWT-based authentication system.

It was created for educational purposes.

Requirements

• Go 1.16+
• Go Modules
• Docker & Docker-Compose

Getting Started

.env files

Before starting, you should create two .env files with environment variables needed to configure the app and pass private secrets, for dev and prod mode.

• .env.local

  APP_PORT=4000
  
  DB_USER=example_dbuser // replace to yours
  DB_PASS=example_dbpass // replace to yours
  DB_NAME=example_dbname // replace to yours
  DB_HOST=pgsql          // addr in docker-compose network
  DB_PORT=5432
  DB_SSLMODE=disable
  
  TOKEN_SECRET=super@HYPER!secret12345 // replace to yours

• .env.prod

  APP_PORT=4000
  GIN_MODE=release
  
  DB_USER=prod_dbuser // replace to yours
  DB_PASS=prod_dbpass // replace to yours
  DB_NAME=prod_dbname // replace to yours
  DB_HOST=localhost   // replace to yours
  DB_PORT=5432        // replace to yours
  DB_SSLMODE=disable
  
  TOKEN_SECRET=super@HYPER!secret12345 // replace to yours

dev mode

1. install deps: go mod download

2. build migration tool: make install-tool-migrate

3. run local postgres: make compose-pgsql

4. update migrations: make migrate-up

5. build dev container: make compose-build

6. run app in dev container (with hot-reload): make compose-up

for debug with dlv replace in docker-compose.yaml command part ./entry.sh watch to ./entry.sh debug.

prod mode

1. build prod container: make prod-build (it creates tasx_app image)

2. update migrations (on target database): make prod-migrate-up

3. run app container: make prod-run

REST API Endpoints

Healthcheck

• GET /healthz

  Response: 200 OK

  {
    "status": "available"
  }

  ---

Authentication

• POST /auth/signup

  Body:

  {
    "name": "John Doe",
    "username": "johndoe777",
    "password": "secret_pass"
  }

  Response: 200 OK

  ---

• POST /auth/login

  Body:

  {
    "username": "johndoe777",
    "password": "secret_pass"
  }

  Response: 200 OK

  {
    "token": <TOKEN>
  }

Task Lists

• POST /api/lists

  Authorization: Bearer <TOKEN>

  Body:

  {
    "title": "list name",
    "description": "list description"
  }

  Response: 200 OK

  ---

• GET /api/lists

  Authorization: Bearer <TOKEN>

  Response: 200 OK

  {
    "lists": [
      {
        "id": <ID>,
        "title": string,
        "description": string
      }
    ]
  }

  ---

• GET /api/lists/:id

  Authorization: Bearer <TOKEN>

  Response: 200 OK

  {
    "id": <ID>,
    "title": string,
    "description": string
  }

  ---

• PUT /api/lists/:id

  Authorization: Bearer <TOKEN>

  Body:

  {
    "title": "Updated Name",      // optional
    "description": "Updated Desc" // optional
  }

  Response: 200 OK

  ---

• DELETE /api/lists/:id

  Authorization: Bearer <TOKEN>

  Response: 200 OK

Tasks of the List

• POST /api/lists/:id/items

  Authorization: Bearer <TOKEN>

  Body:

  {
    "title": "task title",
    "description": "task desc"
  }

  ---

• GET /api/lists/:id/items

  Authorization: Bearer <TOKEN>

  Response: 200 OK

  {
    "tasks": [
      {
        "id": <ID>,
        "title": string,
        "description": string,
        "is_done": boolean
      }
    ]
  }

  ---

Tasks by ID

• GET /api/items/:id

  Authorization: Bearer <TOKEN>

  Response: 200 OK

  {
    "task": {
      "id": <ID>,
      "title": string,
      "description": string,
      "is_done": boolean
    }
  }

  ---

• PUT /api/items/:id

  Authorization: Bearer <TOKEN>

  Body:

  {
    "title": "task title",      // optional
    "description": "task desc", // optional
    "is_done": true             // optional
  }

  Response: 200 OK

  ---

• DELETE /api/items/:id

  Authorization: Bearer <TOKEN>

  Response: 200 OK

  ---