JSON API for Mobile and External Applications

An integration should not depend on web-page markup

An enterprise platform stops being an isolated website when it is connected to a mobile application, a driver's workspace, an internal portal, a terminal, or a partner service. Attempting to use HTML pages for this purpose quickly creates a fragile dependency on design. Direct database access is more dangerous still: an external client begins to repeat business rules, ignore permissions, and depend on the internal storage schema.

Sapphire I.C.D.S. provides a separate integration environment for these tasks: an HTTPS JSON API. It accepts structured requests and returns machine-readable responses, does not render user pages, and does not require a client to understand the server database. The public Roadmap records this environment as a released foundation for native clients and business integrations.

JSON is the exchange format, not the complete architecture

JSON alone does not make an integration reliable. What matters is who defines the available command, how the user is validated, and where business validation is performed. In Sapphire I.C.D.S., the system API handles authentication, while modules publish domain commands through a separate contract. The client supplies an action and data, but the server selects the responsible module, validates the request, and forms the result.

This allows the web interface, mobile application, and external system to use the same domain logic. For example, an operation that saves a delivery result should validate the route, outlet, product, and operator rights in the same way regardless of which screen sent the request. The client is responsible for a usable interface; the module is responsible for process correctness.

Session and identity are validated by the server

The API supports the basic client-session lifecycle: sign-in, retrieval of the current validated principal, access renewal, and sign-out. After successful sign-in, the client receives a short-lived access token and a separate refresh token. A refresh replaces the pair, so the application must store the new pair atomically and must not repeat a successful operation with an old value.

The critical principle is that user, group, or object fields in JSON do not prove authority. The server derives identity from the validated session and only then determines the available data scope. A logistics module, for example, must not show another route because the client supplied a different driver identifier. The relationship to a business role is resolved on the server.

Modules publish only explicit actions

The dedicated API does not automatically expose every Sapphire I.C.D.S. function. A module must implement an API provider and enumerate its supported commands. This allows integrations to be released in stages: safe reads first, then narrow changes, followed by more complex workflows after validation. A module without an external contract does not become available merely because it is installed.

Commands that change state must use requests intended for modification, while retrieval can remain a separate operation. The server returns meaningful result codes for an invalid request, an expired session, access denial, the wrong method, or a temporarily unavailable dependency. The client application receives a defined handling path rather than an HTML error page.

• The mobile client sends only the required data and stores tokens in protected device storage.
• The API environment validates the session, request method, and acceptable input size.
• The module validates domain rules, user scope, and permitted state transitions.
• The database remains behind the server layer and is not exposed directly to the client.

Suitable business scenarios

A JSON API is particularly useful when an employee works away from the main back office. In logistics, this may mean a list of assigned routes, outlet data, and recording a delivered quantity, return, or document state. In accounting, it may mean obtaining a reference list and sending a confirmed operation. In an external application, it can mean reading authorised state and starting a specific command without simulating browser actions.

The public Roadmap identifies logistics, accounting, and field processes as natural directions for development. This does not mean that one universal endpoint already exists for every scenario. Readiness is determined by the API command set of the installed module. Before starting an integration project, the parties should prepare a matrix of operations, data, roles, and versions.

The JSON API is not external MCP

Both environments use structured data, but they serve different classes of clients. The JSON API is intended for mobile and enterprise applications with a predefined user workflow. External MCP is intended for compatible AI clients that discover tools and call them during an agent session. Their permissions and publication policies must not be treated as interchangeable.

The API is also not a remote SQL console, a generator of arbitrary reports, or a promise of access to every table. It provides business commands owned by a module. This level of abstraction is more resilient to changes in the storage schema and safer for long-term maintenance.

What the client application must handle

A native client must correctly handle access-token expiry, refresh-token replacement, sign-out, network loss, and repeated submission. For state-changing operations, it is especially important to distinguish a confirmed rejection from an uncertain transport result. Without agreed idempotency, the client must not automatically retry an action that may have completed on the server. A local cache must not be treated as the source of current rights.

The technical team also defines contract versioning, logging, request limits, and the backward-compatibility strategy. The platform supplies the common modular environment, but the quality of a specific mobile product depends on client discipline and the completeness of the published business contract.

The adoption path

Work should begin with an inventory of user scenarios rather than a list of tables. For every step, the parties define input fields, response, role, data scope, allowed transitions, and repeat behaviour. The module then publishes the minimum command set, the mobile team builds the interface, and joint tests cover both successful and prohibited scenarios.

For a business owner, the outcome is the ability to develop proprietary applications without duplicating server logic. For a technical director, it is a governed integration boundary with common authentication and modular commands. The JSON API extends Sapphire I.C.D.S. beyond the web interface while keeping data, permissions, and process rules inside the authoritative server environment.