/tasx

Example microservice app built with Go

Primary LanguageGo

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