API Contract Rules Between Frontend, Backend, and MAUI

The Dragon Guard ecosystem has three consumers of Wms.Api: the Angular administrative frontend, the MAUI handheld application, and automated integrations. All three share the same endpoint surface with no client-specific forks. This means every change to an API response shape, endpoint path, or field name has the potential to break a client the developer did not test. These rules define what changes are safe, what requires versioning, and what the frontend is forbidden from doing regardless of whether the API would permit it.

Base URL Configuration

The Angular app resolves the backend base URL from three sources, evaluated in order at deployment time:

Development: environment.ts

src/environments/environment.ts sets apiUrl for local development builds. This file is never deployed to production.

// src/environments/environment.ts
export const environment = {
  production: false,
  apiUrl: 'https://localhost:7001'
};

Production build: environment.prod.ts

src/environments/environment.prod.ts sets the default production apiUrl. Angular CLI substitutes this file during ng build --configuration production.

// src/environments/environment.prod.ts
export const environment = {
  production: true,
  apiUrl: 'https://api.dragonguardwms.com'
};

Runtime override: runtime-config.js

src/assets/runtime-config.js is loaded by index.html before the Angular bundle. It can override apiUrl without rebuilding the app — useful for environment-specific Docker deployments.

// src/assets/runtime-config.js  (production override)
window['__env'] = {
  apiUrl: 'https://api.dragonguardwms.com'
};

WmsService checks window['__env']?.apiUrl first and falls back to environment.apiUrl.

Use runtime-config.js when deploying the same Docker image to multiple environments. Baking the URL into environment.prod.ts means a different image per environment; the runtime config avoids that.

Contract Rules

These rules apply to all changes made to Wms.Api, regardless of which client or team requests them:

Rule	Rationale
Never break existing endpoints	Both Angular and MAUI depend on the same surface; a 404 on a renamed path crashes both clients simultaneously
Never rename endpoints without versioning	Create `/api/v1/…` before removing or renaming any path in production
Never remove response fields used by Angular or MAUI	Field removal is a breaking change even if the endpoint path stays the same
Prefer additive changes	New optional fields in a response are safe; existing consumers ignore fields they do not read
All API changes must consider MAUI impact	MAUI ships as a mobile app; rollback requires a new store release; backend changes must be backward compatible
Web must never call handheld-only posting endpoints	Physical execution endpoints are MAUI-only by design; calling them from the web UI violates the responsibility boundary

The API is not currently versioned. Until /api/v1/ is established, treat every endpoint as a public contract. Any change to a path, method, or required field in production requires coordination with the MAUI team before deployment.

Endpoint Inventory

Auth
Receipts
Shipments
Items & Stock
Commercial

Method	Path	Consumer	Notes
`POST`	`/api/Auth/login`	Web, MAUI	Returns JWT + session metadata; no auth header required

Login request body:

{
  "email": "string",
  "password": "string"
}

Login response body:

{
  "token": "string",
  "userId": 0,
  "email": "string",
  "fullName": "string",
  "companies": []
}

The companies array drives company-switcher UI for multi-company tenant admins. is_supreme_admin is derived from JWT claims decoded on the frontend.

Method	Path	Consumer	Notes
`GET`	`/api/ReceivingHeaders`	Web, MAUI	List receipt headers; scoped to `companyId`
`POST`	`/api/ReceivingHeaders`	Web	Create a new receipt document
`GET`	`/api/ReceivingHeaders/{id}`	Web, MAUI	Fetch a single receipt with lines

Physical receipt posting (confirming goods received) is a MAUI-only operation. The web UI creates and edits receipt documents but does not post them.

Method	Path	Consumer	Notes
`GET`	`/api/shipmentheaders`	Web, MAUI	List shipment headers
`POST`	`/api/shipmentheaders`	Web	Create a shipment document
`PUT`	`/api/shipmentheaders`	Web	Update a shipment document
`GET`	`/api/shipmentheaders/{id}`	Web, MAUI	Fetch a single shipment with lines

Shipment confirmation and physical dispatch are MAUI-only. The web creates and modifies shipment documents only.

Method	Path	Consumer	Notes
`POST`	`/api/items/create_item`	Web	Create a new inventory item master
`GET`	`/api/stock/enriched`	Web	Read-only enriched stock view
`GET`	`/api/movements`	Web	Audit movement history
`GET`	`/api/document-sequence?companyId={id}`	Web	Next document sequence number

The frontend must never write to stock endpoints. GET /api/stock/enriched is the only stock endpoint accessible from the web. All stock mutations are performed by MAUI or by server-side business logic triggered through document posting.

Method	Path	Consumer	Notes
`GET`	`/api/customers`	Web	List customers
`POST`	`/api/customers`	Web	Create a customer
`PUT`	`/api/customers`	Web	Update a customer
`GET`	`/api/vendors`	Web	List vendors
`POST`	`/api/vendors`	Web	Create a vendor
`PUT`	`/api/vendors`	Web	Update a vendor
`GET`	`/api/sellers`	Web	List sellers
`POST`	`/api/sellers`	Web	Create a seller
`PUT`	`/api/sellers`	Web	Update a seller
`GET`	`/api/sales-orders`	Web	List sales orders
`POST`	`/api/sales-orders`	Web	Create a sales order
`PUT`	`/api/sales-orders`	Web	Update a sales order
`GET`	`/api/purchase-orders`	Web	List purchase orders
`POST`	`/api/purchase-orders`	Web	Create a purchase order
`PUT`	`/api/purchase-orders`	Web	Update a purchase order

Standard Error Responses

All API errors follow a consistent status-code convention. Angular’s WmsService and the JWT interceptor handle these globally:

HTTP Status	Meaning	Angular behaviour
`400 Bad Request`	Validation error — invalid payload or business rule violation	Display validation message returned in response body
`401 Unauthorized`	Missing, invalid, or expired JWT	JWT interceptor clears `sessionStorage` and redirects to `/auth/login`
`500 Internal Server Error`	Unhandled server exception	Display generic error toast; log to console

403 Forbidden may also be returned by the backend when a valid token lacks the required role (e.g., a company admin calling a supreme endpoint). Angular should treat 403 as a navigation-permission error and redirect to the dashboard, not to the login screen.

API Versioning Strategy

The current API is unversioned. All endpoints live directly under /api/. Before making any breaking change in a production environment, the following versioning strategy must be followed:

Introduce the new versioned path

Add the new endpoint under /api/v1/ alongside the existing /api/ path. Both must function simultaneously. Do not remove the old path yet.

GET /api/ReceivingHeaders/{id}        ← existing (keep working)
GET /api/v1/ReceivingHeaders/{id}     ← new shape

Migrate Angular to the new path

Update WmsService to call the /api/v1/ endpoint. Deploy the Angular update. Verify all Angular flows work against the new path.

Coordinate MAUI migration

Notify the MAUI team. MAUI must release an app update pointing to /api/v1/ before the old path can be removed. This may require a store submission cycle — plan accordingly.

Deprecate and remove the old path

Only after both Angular and MAUI have migrated and the old version is no longer in active use, remove /api/ReceivingHeaders/{id}. Log the removal in the API changelog.

Forbidden Actions from the Frontend

These actions are explicitly prohibited in the Angular frontend regardless of whether a backend endpoint exists to support them:

Forbidden action	Reason
Calling any stock-write or stock-manipulation endpoint	Stock integrity is owned by MAUI and server-side business logic
Calling posting or confirmation endpoints	Physical execution is MAUI-only
Bypassing backend validation with client-side pre-processing	The backend is the authoritative validation layer
Accessing data from another company (cross-tenant reads)	`WmsService` always scopes to `active_company_id`; cross-company calls are never constructed
Hard-coding API paths outside of `WmsService`	All HTTP must flow through the central service to maintain contract traceability

Architecture Overview

Module structure, lazy routing, central service rule, JWT auth flow, and the web/handheld responsibility boundary.

Multitenancy

Tenant vs. SaaS surface separation, session keys, SupremeService endpoints, and the role-based routing model.

Getting Started

Architecture

Core Modules

Admin & Operations

RFID & Supreme Admin

Developer Guide

API Contract Rules Between Frontend, Backend, and MAUI

Base URL Configuration

Contract Rules

Endpoint Inventory

Standard Error Responses

API Versioning Strategy

Forbidden Actions from the Frontend

Architecture Overview

Multitenancy

Build docs developers (and LLMs) love

Getting Started

Architecture

Core Modules

Admin & Operations

RFID & Supreme Admin

Developer Guide

Documentation Index

​Base URL Configuration

​Contract Rules

​Endpoint Inventory

​Standard Error Responses

​API Versioning Strategy

​Forbidden Actions from the Frontend

Architecture Overview

Multitenancy

Build docs developers (and LLMs) love

Base URL Configuration

Contract Rules

Endpoint Inventory

Standard Error Responses

API Versioning Strategy

Forbidden Actions from the Frontend