Skip to content

README.md

Latest commit

 

History

History
83 lines (58 loc) · 6.4 KB

README.md

File metadata and controls

83 lines (58 loc) · 6.4 KB
Raw

API Module Specifications

Canonical one-to-one API module index

Each API document describes the optional module-{independent-module-name}-api presentation package matching exactly one independent domain module. Applications compose these packages into unified external APIs without moving ownership.

Nuxt clients consume these API contracts through the matching one-to-one packages under Nuxt 4 implementations. They must use documented routes, schemas, authentication, permissions, tenant/team context, pagination, errors, idempotency, and versioning; they must not call private Laravel implementation details.

Implementation plan

For every listed module, implement module-{independent-module-name}-api as a thin Laravel 13 transport adapter over the matching module-{independent-module-name} core package. Keep controllers and route registration small; delegate writes to typed core actions, reads to core queries/read models, and authorization to the core policy boundary after request validation. Define OpenAPI 3.1 schemas, operation IDs, audiences, scopes, rate limits, pagination, field visibility, errors, idempotency, optimistic concurrency, and deprecation metadata as versioned contracts.

Use PHP 8.5 strict types, Form Requests or dedicated validators, API Resources/DTOs, Sanctum or approved service identity, and RFC 9457 Problem Details. Resolve tenant/team context from trusted authentication and enforce concealment-safe authorization. Queue slow, bulk, provider-dependent, and retryable work through idempotent operation resources. Test allowed and denied access, wrong tenant, scopes, validation, hidden fields, concurrency, throttling, contracts, schema drift, and failure recovery without querying core-private tables.

Sanctum authentication

Third-party clients authenticate with Laravel Sanctum personal access tokens. First-party SPAs should use Sanctum's cookie-based SPA authentication instead of storing API tokens in browser code. See the Laravel Sanctum documentation for the complete configuration reference.

Issue a token

Install and configure Sanctum in the application, then expose a protected, rate-limited token-issuance action. Jetstream applications may use their API-token UI; custom clients should use an application-owned action that requires an authenticated user and recent authentication:

$token = $request->user()->createToken(
    name: $request->string('device_name')->toString(),
    abilities: ['genealogy.tree.read'],
)->plainTextToken;

return ['token' => $token];

Display the plain-text token once. Store only the token securely on the client; Sanctum stores a hash in the database. Never log, commit, or include tokens in URLs.

Call a protected endpoint

Send the token in the Authorization header as a Bearer token. API routes must use the Sanctum guard:

// bootstrap/app.php
use Illuminate\Foundation\Configuration\Middleware;
use Laravel\Sanctum\Http\Middleware\CheckAbilities;

->withMiddleware(function (Middleware $middleware): void {
    $middleware->alias(['abilities' => CheckAbilities::class]);
})

// routes/api.php
Route::get('/trees', TreeIndexController::class)
    ->middleware(['auth:sanctum', 'abilities:genealogy.tree.read']);

Example request:

curl --fail-with-body \\
  -H 'Accept: application/json' \\
  -H 'Authorization: Bearer YOUR_SANCTUM_TOKEN' \\
  https://api.example.test/api/v1/trees

The route middleware verifies authentication and token ability. The controller or domain action must still apply the relevant policy and team checks, including resource ownership and current-team membership. A valid token alone never grants access to every resource.

Revoke and expire tokens

Provide an authenticated token-management action to revoke the current token or all tokens. Configure a finite expiration period for production integrations, document rotation, and schedule expired-token pruning. Treat a leaked token as a credential: revoke it immediately and issue a replacement.

For a first-party SPA, use /sanctum/csrf-cookie, session login, and auth:sanctum; do not issue long-lived personal access tokens to browser JavaScript.

Application API modules Source
Accounting 105 ACCOUNTING.md
Automation 11 AUTOMATION.md
Billing 16 BILLING.md
Browser Game 15 BROWSER-GAME.md
CMS 81 CMS.md
Control Panel 15 CONTROL-PANEL.md
CRM 95 CRM.md
Ecommerce 105 ECOMMERCE.md
Genealogy 14 GENEALOGY.md
Maintenance 14 MAINTENANCE.md
Real Estate 15 REAL-ESTATE.md
SAP 16 SAP.md
Social Network 15 SOCIAL-NETWORK.md