REST API Endpoints

REST API Endpoints

Complete reference of auto-generated HTTP endpoints. All endpoints are generated automatically from service contracts.

User Management

Create User

Create a new user account.

POST /api/users

Request Body:

{
  "email": "user@example.com",
  "firstName": "John",
  "lastName": "Doe"
}

Response (201 Created):

{
  "userId": "user-123",
  "email": "user@example.com",
  "createdAt": "2025-11-15T12:00:00Z"
}

Required Permissions: users:create

---

Get User

Retrieve a user by ID.

GET /api/users/:userId

Path Parameters:

• userId - User identifier

Response (200 OK):

{
  "userId": "user-123",
  "email": "user@example.com",
  "firstName": "John",
  "lastName": "Doe"
}

Required Permissions: users:read

---

Update User

Update user information.

PUT /api/users/:userId

Path Parameters:

• userId - User identifier

Request Body:

{
  "email": "newemail@example.com",
  "firstName": "Jane",
  "lastName": "Smith"
}

Response (200 OK):

{
  "userId": "user-123",
  "email": "newemail@example.com",
  "firstName": "Jane",
  "lastName": "Smith",
  "updatedAt": "2025-11-15T12:30:00Z"
}

Required Permissions: users:update

---

Delete User

Permanently delete a user account.

DELETE /api/users/:userId

Path Parameters:

• userId - User identifier

Response (204 No Content)

Required Permissions: users:delete

---

List Users

Retrieve a paginated list of users.

GET /api/users?page=1&pageSize=20&role=admin

Query Parameters:

• page (optional) - Page number (default: 1)
• pageSize (optional) - Items per page (default: 20, max: 100)
• role (optional) - Filter by role
• search (optional) - Search by name or email

Response (200 OK):

{
  "users": [
    {
      "userId": "user-123",
      "email": "user@example.com",
      "firstName": "John",
      "lastName": "Doe"
    }
  ],
  "page": 1,
  "pageSize": 20,
  "totalCount": 100,
  "totalPages": 5
}

Required Permissions: users:read

---

Authentication

Login

Authenticate and receive JWT tokens.

POST /api/login

Request Body:

{
  "email": "user@example.com",
  "password": "securepassword123"
}

Response (200 OK):

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": 3600,
  "user": {
    "userId": "user-123",
    "email": "user@example.com",
    "name": "John Doe"
  }
}

Required Permissions: None (public endpoint)

---

Logout

Invalidate user session.

POST /api/logout

Request Body:

{
  "userId": "user-123"
}

Response (200 OK):

{
  "success": true
}

Required Permissions: Authenticated user

---

Refresh Token

Obtain a new access token using a refresh token.

POST /api/refresh-token

Request Body:

{
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Response (200 OK):

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": 3600
}

Required Permissions: Valid refresh token

---

External Authentication

Authenticate using external providers (Google, GitHub, etc.)

POST /api/login/external

Request Body:

{
  "provider": "google",
  "idToken": "ya29.a0AfH6SMBx..."
}

Response (200 OK):

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": 3600,
  "user": {
    "userId": "user-456",
    "email": "user@gmail.com",
    "name": "John Doe"
  }
}

Supported Providers:

• google - Google OAuth
• github - GitHub OAuth
• microsoft - Microsoft OAuth

Required Permissions: None (public endpoint)

---

Error Responses

All endpoints may return these standard error responses:

400 Bad Request

Validation failed or malformed request.

{
  "error": "Validation failed",
  "code": "VALIDATION_ERROR",
  "details": {
    "email": "Invalid email format",
    "firstName": "First name is required"
  }
}

---

401 Unauthorized

Missing or invalid authentication token.

{
  "error": "Authentication required",
  "code": "UNAUTHORIZED"
}

---

403 Forbidden

Insufficient permissions to perform the operation.

{
  "error": "Permission denied",
  "code": "PERMISSION_DENIED",
  "required": ["users:create"],
  "actual": ["users:read"]
}

---

404 Not Found

Requested resource or handler not found.

{
  "error": "Handler not found for message type: UnknownCommand",
  "code": "HANDLER_NOT_FOUND"
}

Or:

{
  "error": "User not found",
  "code": "NOT_FOUND"
}

---

500 Internal Server Error

Unexpected server error.

{
  "error": "Internal server error",
  "code": "INTERNAL_ERROR",
  "correlationId": "abc-123-def"
}

Use the correlationId for troubleshooting in logs and traces.

---

Pagination

List endpoints support pagination using query parameters:

GET /api/users?page=2&pageSize=50

Parameters:

• page - Page number (1-indexed, default: 1)
• pageSize - Items per page (default: 20, max: 100)

Response includes pagination metadata:

{
  "items": [...],
  "page": 2,
  "pageSize": 50,
  "totalCount": 250,
  "totalPages": 5,
  "hasNext": true,
  "hasPrevious": true
}

---

Filtering and Sorting

List endpoints may support filtering and sorting:

GET /api/users?role=admin&sort=createdAt&order=desc

Common Query Parameters:

• sort - Field to sort by
• order - Sort direction (asc or desc)
• Resource-specific filters (e.g., role, status, search)

Check individual endpoint documentation for supported filters.

---

Field Selection

Some endpoints support field selection to reduce payload size:

GET /api/users/:userId?fields=userId,email,firstName

Response:

{
  "userId": "user-123",
  "email": "user@example.com",
  "firstName": "John"
}

---

Endpoint Discovery

To discover all available endpoints, use the service discovery endpoint:

GET /api/discovery/contracts

Returns all service contracts with their generated endpoints.

---

Next Steps

• API Examples - Working code examples in multiple languages
• Authentication - JWT tokens and permissions
• Error Handling - Comprehensive error reference