API Calls Documentation

Table of Contents

1. Introduction
2. Internal API Routes

Introduction

An overview of the API calls that we make in the app and its purpose.

This dashboard application primarily uses internal API routes for status checking, authentication, and cache management. All routes are Next.js API routes that serve as endpoints within the application.

Internal API Routes

These are Next.js API routes that serve as endpoints within the application or proxy to external services.

Status Routes

/api/status

• Description: Get basic status information.
• Method: GET
• Location: src/app/api/status/route.ts
• Returns: {status: 'ok'}

/api/status/all

• Description: Get comprehensive status information including app info, API status, configs, cache, and user token.
• Method: GET
• Location: src/app/api/status/all/route.ts
• Returns: Complete status information with app name, version, NextJS version, React version, etc.
• Headers:
  • x-timezone: Optional timezone header (defaults to “America/New_York”)

/api/status/api

• Description: Get the status of the external API connection.
• Method: GET
• Location: src/app/api/status/api/route.ts
• Returns: API connection status information

/api/status/configs

• Description: Get the status of configuration services.
• Method: GET
• Location: src/app/api/status/configs/route.ts
• Returns: Configuration status including whether config API login is available

/api/status/cache

• Description: Get the status of cache tables (AppCache and ConfigCache).
• Method: GET
• Location: src/app/api/status/cache/route.ts
• Returns: Cache status including table status, item count, creation date/time
• Headers:
  • x-timezone: Optional timezone header (defaults to “America/New_York”)

/api/status/user-token/check

• Description: Validate and check the user token.
• Method: GET
• Location: src/app/api/status/user-token/check/route.ts
• Authentication: Reads token from currentUser cookie
• Returns: Token validation result and user information

/api/status/user-token/display

• Description: Get user token display information.
• Method: GET
• Location: src/app/api/status/user-token/display/route.ts
• Authentication: Reads token from currentUser cookie
• Headers:
  • x-timezone: Optional timezone header (defaults to “America/Montreal”)
• Returns: User token information with decoded payload

/api/status/user-token/expected

• Description: Get expected user token information.
• Method: GET
• Location: src/app/api/status/user-token/expected/route.ts
• Returns: Expected token structure and information

Authentication Routes

/api/oauth/authorize

• Description: Initiate OAuth 2.0 authorization code flow.
• Method: GET
• Location: src/app/api/oauth/authorize/route.ts
• Flow: Authorization Code Flow (OAuth 2.0)
• Configuration: Requires oauth_client_id parameter from configs

/api/oauth/callback

• Description: Handle OAuth 2.0 callback after authorization.
• Method: GET
• Location: src/app/api/oauth/callback/route.ts
• Configuration: Requires oauth_client_id and oauth_client_secret parameters from configs

/api/logout

• Description: Handle user logout.
• Method: GET
• Location: src/app/api/logout/route.ts
• Returns: Logout response

/api/config-login

• Description: Handle configuration-based login.
• Method: POST
• Location: src/app/api/config-login/route.ts
• Returns: Login response

Cache Management

/api/clear-cache

• Description: Clear all cache tables (requires ROLE_ADMIN).
• Method: DELETE
• Location: src/app/api/clear-cache/route.ts
• Authorization: Requires ROLE_ADMIN role
• Actions: Deletes all entries from AppCache and ConfigCache tables
• Returns: Success or error response