182 lines
4.4 KiB
Markdown
182 lines
4.4 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
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
|
|
|
|
```json
|
|
{
|
|
"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
|
|
|
|
```bash
|
|
go run ./cmd/api
|
|
```
|
|
|
|
Or with Task:
|
|
|
|
```bash
|
|
task run
|
|
```
|
|
|
|
Then open:
|
|
|
|
```text
|
|
http://localhost:8080/
|
|
```
|
|
|
|
Optional env vars:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```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:
|
|
|
|
```bash
|
|
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`
|