AdminConsole
Tutorials/Intermediate
Intermediate35 minREST

Call Mappls safely from a trusted server

Exchange OAuth client credentials, keep tokens in bearer headers, call typed Search and Route operations, preserve provenance, and bound retry.

By the endA credential-safe live server boundary with typed errors, timeout, retry, and provider provenance.
Real-world scenario

Build against an explicit contract

A trusted backend must call Search, Route, and InTouch without placing client credentials in URLs, logs, browsers, or retry queues.

A Mappls developer projectA restricted REST applicationFixture data with no production credentialsA request, aggregate, or correlation ID strategy
Step 1

Define the user and system contract

A trusted backend must call Search, Route, and InTouch without placing client credentials in URLs, logs, browsers, or retry queues. Record the region, data freshness, latency budget, privacy purpose, credential owner, and fallback before choosing an SDK or endpoint.

Step 2

Own credentials in one adapter

Load client identity from the secret manager, exchange over HTTPS, cache the bearer token before expiry, and deduplicate concurrent refreshes.

Search & Places · SDK or product slice
import { createMapplsClientFromEnvironment } from "@mappls/server-sdk";

// MAPPLS_STATIC_KEY is applied using the current documented query contract.
// Keep the restricted key inside this trusted server process.
const mappls = createMapplsClientFromEnvironment();
const suggestions = await mappls.autosuggest({
  query: "coffee",
  region: "IND"
});
Step 3

Wrap provider calls

Validate inputs, send bearer headers, cap body and timeout, preserve provider request identity, and map status/body to redacted typed errors.

Step 4

Retry only safe work

Retry bounded idempotent reads on transient status or timeout with jitter and Retry-After; reconcile writes by idempotency identity instead of blind retry.

Step 5

Prove the production behavior

Automate the happy path and every named failure. The release is ready only when one token refresh serves concurrent calls; logs never contain credentials or provider bodies; timeouts and rate limits produce typed retry guidance. Capture provider request identity without logging credentials or unnecessary precise location.

Recovery design

Failure modes you must exercise

token endpoint denied or unavailable

Fail fast with a typed, user-safe outcome and preserve the original request identity.

provider returns 429 or 5xx

Keep the last verified state, mark freshness honestly, and retry only within the documented idempotency boundary.

timeout occurs after a stateful provider commit

Reconcile durable local and provider evidence before declaring success or issuing a compensating command.

Never turn uncertainty into success

Timeout after a stateful command is an unknown outcome. Query by provider/idempotency identity or wait for authoritative events; do not blindly retry a new command.

Acceptance criteria

Definition of done

one token refresh serves concurrent callslogs never contain credentials or provider bodiestimeouts and rate limits produce typed retry guidance

REST production checks

Credentials never reach a browser or mobile bundleTimeout, retry, and idempotency policies are explicitCoordinates, addresses, and identifiers have data-retention rulesEvery operation is attributable in logs and usage reporting
Grounded implementation

Continue from source, contracts, and a full app

These links resolve to repository-derived evidence; unsupported package names and endpoints are not filled in from guesswork.

Study the complete Connected fleet trip state machine
Tutorial complete

Run it, break it, then observe it

Start with fixture credentials, execute the failure plan, and use request logs, usage, webhook evidence, and operational metrics before promoting traffic.