API Calls Documentation

Introduction

An overview of the API calls that we make in the app and its purpose. The API url is : https://demo-ecs.phpreaction.com/open-api/v3  The API Doc : https://phpreaction.com/utilisation-apiv4-phpreaction/ 

All external API calls go through the /api/callOut route which acts as a proxy to the external API.

External API Endpoints

Users

https://account.solidservice.link/api/v1/users/\{id\}/preferences 

• Description: Update user preferences (theme, locale, timezone).
• Method: PATCH
• Used in: src/hooks/usePreferences.tsx - handleSubmit()
• Request Body:

{
  "preferences": {
    "theme": "system|light|dark",
    "locale": "fr|en",
    "timezone": "America/New_York"
  },
  "csrf": "csrf_token"
}

• Role: (Role information to be determined)

https://account.solidservice.link/api/v1/users/\{id\} 

• Description: Update user account information (username, email, password, etc.).
• Method: PATCH
• Used in: src/utils/apiUser.ts - updateAccount()
• Request Body:

{
  "username": "new_username",
  "email": "new_email@example.com",
  "plainPassword": "new_password",
  "csrf": "csrf_token"
}

• Role: Editing username and email is only allowed for users with ROLE_SUPERADMIN. Other fields can be updated by any authenticated user. See User Roles.

https://account.solidservice.link/api/v1/users/logged_user/change_password 

• Description: Change the password for the currently logged-in user.
• Method: PATCH
• Used in: src/components/ResetPassword/index.tsx - handleSubmit()
• Request Body:

{
  "csrf": "csrf_token",
  "currentPassword": "current_password",
  "plainPassword": "new_password",
  "plainPasswordConfirmation": "new_password"
}

• Role: (Role information to be determined)

Authentication (External Service)

{tenant}.login.phpr.link/2fa_check

• Description: Verify 2FA authentication code (called via internal /api/2fa route).
• Method: POST
• Used in: src/app/api/2fa/route.ts - POST handler
• Request Body:

{
  "auth_code": "2fa_code"
}

• Headers: Authorization: Bearer {jwt_token}
• Returns: Access token, refresh token, and refresh token expiration

Internal API Routes

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

/api/callOut

• Description: Proxy route for all external API calls. Handles GET, POST, and PATCH requests.
• Methods: GET, POST, PATCH
• Location: src/app/api/callOut/route.ts
• Usage: All CallAPI() calls go through this route

User Routes

/api/user

• Description: Get user information for the currently authenticated user.
• Method: GET
• Location: src/app/api/user/route.ts
• Authentication: Reads token from currentUser cookie
• Returns: User information object

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)

/api/oauth/callback

• Description: Handle OAuth 2.0 callback after authorization.
• Method: GET
• Location: src/app/api/oauth/callback/route.ts

/api/logout

• Description: Handle user logout.
• Method: POST
• Location: src/app/api/logout/route.ts

/api/config-login

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

/api/2fa

• Description: Handle 2FA verification with rate limiting and reCAPTCHA validation.
• Method: POST
• Location: src/app/api/2fa/route.ts
• Request Body:

{
  "code": "2fa_code",
  "captchaToken": "recaptcha_token"
}

• Rate Limiting: Maximum 3 requests per 10 seconds per IP address
• Security Features:
  • CSRF token validation
  • reCAPTCHA verification
  • Rate limiting
  • JWT token validation
• Returns: Success status, MFA completion status, and redirect URL
• Cookies Set:
  • currentUser: Access token
  • access_expiration: Token expiration timestamp
  • refresh_token: Refresh token
  • refresh_expiration: Refresh token expiration timestamp

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.

/api/status/api

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

/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

/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

/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

/api/status/user-token/expected

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

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