Documentation

Complete guide to using Winvest Core API services

Getting Started

Winvest Core API exposes health probes, authentication flows, and account endpoints over REST. Use it to wire upstream customer portals or internal tools against a consistent contract.

Base URL: http://localhost:8080
API Version: /api/v1
Swagger UI: http://localhost:8080/api-docs/index.html

Health & Diagnostics

Use these probes for readiness, liveness, and infrastructure checks. They are also duplicated under /api/v1 for ingress controllers that route everything through the API prefix.

Health Check Endpoints

GET /healthz

Check service health status with version information.

curl http://localhost:8080/healthz
GET /readyz

Readiness probe for Kubernetes/container orchestration.

curl http://localhost:8080/readyz
GET /liveness

Liveness probe for Kubernetes/container orchestration.

curl http://localhost:8080/liveness

Authentication

All account APIs require a bearer token generated via the JWE-based login flow. Tokens are short lived, so refresh often or wrap calls with a background job.

Login

POST /api/v1/auth/login

Send domain-qualified credentials to receive an access token.

Request body:

{
  "username": "john.doe",
  "password": "password123",
  "domain": "example.com"
}

Curl example:

curl -X POST http://localhost:8080/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"john.doe","password":"password123","domain":"example.com"}'

Sample response:

{
  "data": {
    "token": "token",
    "type": "Bearer",
    "expires_in": 0
  },
  "message": "Created"
}

Logout & Reset Password

Remember: Always persist the returned token securely (e.g., encrypted at rest) and transmit it only via TLS.

Account Management

Account endpoints surface internal customer metadata. Both routes require a bearer token from the login call.

GET /api/v1/accounts

Returns the available accounts for the authenticated domain. Pagination and filters are planned; for now the endpoint streams the entire dataset.

curl http://localhost:8080/api/v1/accounts \
  -H "Authorization: Bearer <token>"
GET /api/v1/accounts/:id

Fetches details for a specific account identifier.

curl http://localhost:8080/api/v1/accounts/USER-123 \
  -H "Authorization: Bearer <token>"
Tip: Inject the Authorization header through your reverse proxy (Traefik/Nginx) when possible so downstream services never see raw credentials.

Examples

Login via curl

TOKEN=$(curl -s -X POST http://localhost:8080/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"john.doe","password":"password123","domain":"example.com"}' \
  | jq -r '.data.token')

Go client: list accounts

package main

import (
    "fmt"
    "io"
    "net/http"
    "os"
)

func main() {
    token := os.Getenv("WINVEST_TOKEN")
    req, _ := http.NewRequest("GET", "http://localhost:8080/api/v1/accounts", nil)
    req.Header.Set("Authorization", "Bearer "+token)

    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}

Error Handling

The API uses standard HTTP status codes:

Status Code Description
200 Success
400 Bad Request - Invalid parameters
404 Not Found - Symbol or resource not found
500 Internal Server Error
Note: Authentication failures return HTTP 400 responses with structured validation details in the error field.

Rate Limiting

The API implements rate limiting to ensure fair usage:

Best Practices

Additional Resources