An API is a promise. Once a mobile app or a partner system depends on it, you cannot change it as freely as an internal screen. Many of our projects expose APIs, from courier and crew mobile apps to partner integrations on logistics and booking platforms. This article shares the design habits that keep those promises easy to keep.
Design the resources, not the screens, and version early
Model your API around business concepts such as orders, shipments, customers and invoices, and use consistent plural nouns, HTTP methods and status codes. Avoid building endpoints around the exact needs of today's screen, because the next app version will need something different.
GET /api/v1/shipmentslists shipments, with filters and pagination.POST /api/v1/shipmentscreates one.GET /api/v1/shipments/{id}returns one.PATCH /api/v1/shipments/{id}updates part of it.
When an action does not fit the pattern, such as cancelling a shipment, a clearly named action endpoint is better than overloading an update.
Version from the first day
Mobile apps are the hardest clients to update, because users do not upgrade immediately and some never do. Put a version in the path, such as /api/v1, from the first release. Within a version, only make additive changes: new optional fields, new endpoints, new values that old clients can ignore. When you must break compatibility, release a new version and keep the old one running for a published period.
Use API resources for stable output
In Laravel, Eloquent API resources give you one place that decides exactly what each response contains. They stop internal column renames from leaking into the contract, and they make it easy to hide fields by role.
Authentication and authorization
Choose the mechanism that suits the client. Token-based authentication through Laravel Sanctum works well for first-party mobile apps and single-page front ends. Partner systems that call your API from servers usually need long-lived keys that can be rotated and revoked individually, with scopes that limit what each key can do.
Authorize every request
Authentication tells you who is calling. Authorization decides what they may touch. Check ownership and role on every endpoint with policies, and never trust an identifier sent by the client without verifying it belongs to the caller. In multi-tenant systems, scope every query by tenant.
Rate limit by client
Apply rate limits per token or key, with clear response headers. A single buggy partner script should not be able to slow down your mobile users.
Make lists and errors predictable
Paginate everything that can grow
Return lists in pages with a consistent structure, and cap the page size. For feeds that change quickly, cursor-based pagination is more reliable than page numbers, because new records do not shift the results under the user's thumb.
Use one error format
Clients should be able to handle every failure in the same way. Return the right HTTP status code, a short machine-readable code and a human-readable message. For validation failures, list the field errors in a predictable structure.
{
"message": "The given data was invalid.",
"code": "validation_failed",
"errors": {
"phone": ["The phone field is required."]
}
}Never expose stack traces, SQL or internal paths. Log them on the server and return a reference identifier the client can quote to your support team.
Design for unreliable networks
Mobile users lose signal in lifts and on country roads, and partner systems retry when they do not receive a response. Your API will see duplicate requests, so plan for them.
- Idempotency keys. Let clients send a unique key with requests that create money-related or order-related records. If the same key arrives again, return the original result rather than creating a second record.
- Small payloads. Return only what the screen needs, and support field selection or lightweight list views.
- Conditional requests. Use ETags or timestamps so apps can skip downloading unchanged data.
- Offline-friendly sync. For field apps, accept batches of changes with client timestamps and define clear conflict rules.
Webhooks for partners
Partners prefer to be told about events rather than poll for them. Offer webhooks for key events such as order created or shipment delivered. Sign each request so receivers can verify its origin, retry failed deliveries with backoff, and give partners a log where they can see what was sent and replay it.
Document it and test it
An undocumented API is a support burden. Publish an OpenAPI description or a clear reference with example requests and responses, and keep it in the same repository so changes to code and documentation are reviewed together. Back it with feature tests that call the real endpoints and assert on status codes, structure and permissions. Those tests become your guard against accidental breaking changes.
If you are planning a mobile app, a partner portal or an integration between your systems, we can design and build the API with you. See our projects and services, or get in touch with Narmar.
