abuse-registration-api-golang/README.md

Golang API Example: Abuse Registration API

In-memory API example, resets to the base dataset every 10 minutes. 100% self contained binary

Quick Start

I use Taskfile (modern GNU Make iteration) for building and deploying.

for like resbuilding binaries after code changes, I prefer to use reflex by cespare. I have no idea if this works for windows. I guess it should as it is Golang? The tool is baked into this repository with no deps just run

go tool reflex \
  -r '^(cmd|internal|templates|static)/.*\.(go|html|css|js)$' \
  -s -- sh -c 'go tool task dev-start-api'

this starts the server on localhost:8080 by default, can be changed with something like go run ./cmd/api -port :19988

JSON Model

{
  "id": "bb8d39a6-8fef-48af-9f9c-27a41c8f8baf",
  "registered_at": "1989-04-13T15:22:00Z",
  "gender": "female",
  "location": "Tórshavn",
  "abuse_type": "psychological",
  "status": "new"
}

id is generated by the server as a UUID. registered_at defaults to time.Now().UTC() when omitted on create or update.

Run locally

go run ./cmd/api

Or with Task:

task run

Then open:

http://localhost:8080/

Optional env vars:

PORT=:9999 JWT_SECRET=change-me RESET_INTERVAL=10m go run ./cmd/api

Demo users

User	Password	Role	Access
reader	reader-password	Reader	Read protected endpoints
admin	admin-password	Admin	Full create/read/update/delete and manual reset

Auth workflow

Use curl or PowerShell. If using the website hosted api, replace localhost:8080 with https://go-api.poc.fló.fo Reader with curl:

READER_TOKEN=$(curl -s -X POST http://localhost:8080/login \
  -H 'Content-Type: application/json' \
  -d '{"user_name":"reader","password":"reader-password"}' \
  | sed -n 's/.*"token":"\([^"]*\)".*/\1/p')

curl -s 'http://localhost:8080/api/v1/registrations?location=Tórshavn&limit=5' \
  -H "Authorization: $READER_TOKEN"

curl -s 'http://localhost:8080/api/v1/registrations?gender=female&abuse_type=psychological&status=open&limit=10' \
  -H "Authorization: $READER_TOKEN"

curl -s 'http://localhost:8080/api/v1/registrations?from=1989-01-01&to=1990-01-01&offset=20&limit=10' \
  -H "Authorization: $READER_TOKEN"

Reader with PowerShell:

$reader = Invoke-RestMethod `
  -Method Post `
  -Uri "http://localhost:8080/login" `
  -ContentType "application/json" `
  -Body '{"user_name":"reader","password":"reader-password"}'

$READER_TOKEN = $reader.token

Invoke-RestMethod `
  -Uri "http://localhost:8080/api/v1/registrations?location=Tórshavn&limit=5" `
  -Headers @{Authorization=$READER_TOKEN}

Admin workflow:

ADMIN_TOKEN=$(curl -s -X POST http://localhost:8080/login \
  -H 'Content-Type: application/json' \
  -d '{"user_name":"admin","password":"admin-password"}' \
  | sed -n 's/.*"token":"\([^"]*\)".*/\1/p')

CREATED_ID=$(curl -s -X POST http://localhost:8080/api/v1/registrations \
  -H "Authorization: $ADMIN_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"gender":"unknown","location":"Tórshavn","abuse_type":"psychological","status":"new"}' \
  | sed -n 's/.*"id":"\([^"]*\)".*/\1/p')

curl -s -X PUT "http://localhost:8080/api/v1/registrations/$CREATED_ID" \
  -H "Authorization: $ADMIN_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"gender":"female","location":"Skopun","abuse_type":"digital","status":"referred"}'

curl -s -X DELETE "http://localhost:8080/api/v1/registrations/$CREATED_ID" \
  -H "Authorization: $ADMIN_TOKEN"

Endpoint behavior

Public:

• GET /health
• POST /login
• GET /demo/registrations

Protected read:

• GET /api/v1/categories
• GET /api/v1/locations
• GET /api/v1/registrations
• GET /api/v1/registrations/{uuid}

Admin create/read/update/delete:

• POST /api/v1/registrations
• PUT /api/v1/registrations/{uuid}
• DELETE /api/v1/registrations/{uuid}
• POST /api/v1/reset

Allowed values

Allowed gender values:

• female
• male
• non_binary
• unknown

Allowed abuse_type values:

• physical
• psychological
• sexual
• economic
• material
• digital
• stalking
• threats
• honor_related

Filters for GET /api/v1/registrations and /demo/registrations:

• abuse_type
• gender
• location
• status
• from and to, matched against registered_at, accepting YYYY-MM-DD or RFC3339 values
• search
• limit
• offset