API Reference

This document provides details on the HTTP API endpoints available in the GoApp service.

The base URL for the main application server is http://localhost:8080 by default.

User API

Create User

Creates a new user in the system.

• Endpoint: /users
• Method: POST
• Description: Registers a new user with the provided details. The ID is generated by the server.

Request Body:

{
  "FullName": "string",
  "Email": "string (unique)",
  "Phone": "string (optional)",
  "ContactAddress": "string (optional)"
}

Example Request:

curl -X POST http://localhost:8080/users \
-H "Content-Type: application/json" \
-d '{
  "FullName": "Jane Doe",
  "Email": "jane.doe@example.com"
}'

Success Response (200 OK):

{
    "data": {
        "ID": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
        "FullName": "Jane Doe",
        "Email": "jane.doe@example.com",
        "Phone": "",
        "ContactAddress": ""
    }
}

Error Responses:

• 400 Bad Request: If the request body is invalid JSON or fails validation (e.g., missing FullName or Email).
• 409 Conflict: If a user with the provided email already exists.
• 500 Internal Server Error: If there is a problem saving the user to the database.

Get User by Email

Retrieves a user's details by their email address.

• Endpoint: /users/:email
• Method: GET
• Description: Fetches a single user record that matches the given email address.

URL Parameters:

• email (string, required): The email address of the user to retrieve.

Example Request:

curl http://localhost:8080/users/jane.doe@example.com

Success Response (200 OK):

{
    "data": {
        "ID": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
        "FullName": "Jane Doe",
        "Email": "jane.doe@example.com",
        "Phone": "",
        "ContactAddress": ""
    }
}

Error Responses:

• 404 Not Found: If no user with the specified email exists.
• 500 Internal Server Error: If there is a problem querying the database.

General API

Root / Hello World

Returns a simple greeting. Can return either HTML or JSON based on the Content-Type header.

• Endpoint: /
• Method: GET

Example Request (HTML):

curl http://localhost:8080/

Returns an HTML page with the message "Welcome to the Home Page!".

Example Request (JSON):

curl -H "Content-Type: application/json" http://localhost:8080/

Returns {"data":"hello world"}.

Health Responder

The health check and monitoring endpoints are served on a separate port, 2000 by default.

Health Check

Provides status information about the application and its dependencies.

• Endpoint: /-/health
• Method: GET
• Port: 2000

Example Request:

curl http://localhost:2000/-/health

Success Response (200 OK):

{
    "commit": "<git commit hash>",
    "dependencies": {
        "postgres": {
            "status": "OK"
        }
    },
    "env": "testing",
    "releasedOn": "...",
    "startedAt": "...",
    "status": "all systems up and running",
    "version": "v0.1.0"
}