API Development Guide: REST, GraphQL, Security & Cost

Every time your website takes a payment, your mobile app loads an order history, or your CRM updates when a form is submitted, an API is doing the work. An API (Application Programming Interface) is the contract that lets two pieces of software talk to each other: what can be asked for, in what format, by whom, and what happens when something goes wrong.

A well-built API makes a business faster: new apps, partners and tools plug in without rework. A badly built one quietly becomes the most expensive part of your system, because every integration built on top of it inherits its problems. This guide covers how to plan, design, secure, build and run an API, with practical Laravel examples and the decisions that matter most for cost.

What API Development Involves

API development is more than writing endpoints. A production API covers six pieces of work:

1. Contract design: resources, fields, URLs, request and response formats, error structure.
2. Authentication and authorization: who is calling, and what they are allowed to see and change.
3. Business logic: validation, rules, calculations and side effects such as emails or invoices.
4. Integrations: the third-party services your API calls (payments, CRM, accounting, shipping).
5. Documentation and testing: so other developers, and your future self, can use it safely.
6. Operations: rate limiting, logging, monitoring, alerting and versioning over time.

Quotes that only cover item three are why API projects run over budget. When you compare proposals, check that all six are included.

Why Your Business Needs a Proper API

One backend for every channel

A single API can serve your website, a mobile app, an internal admin panel and partner systems. Business rules such as pricing, stock levels and discounts live in one place, so they cannot drift apart between channels.

Integrations instead of rebuilding

You do not need to build payment processing, email delivery or accounting. Stripe, PayPal, SendGrid, Xero, QuickBooks, HubSpot and shipping carriers all expose APIs. Integrating them is usually a fraction of the cost of building the equivalent, and you inherit their compliance work (for example PCI DSS for card payments).

Automation of manual work

Re-keying orders into an accounting package, exporting CSVs between systems, copying leads into a CRM: these are API problems. Connecting the systems removes the manual step and the errors that come with it. If this is your main goal, see my business automation and API integration services.

Room to grow

When a new sales channel, marketplace or partner appears, a clean API lets you connect it in days instead of re-architecting. That flexibility is the long-term return on getting the API right.

Choosing an API Style: REST vs GraphQL vs gRPC

The architectural style is one of the hardest decisions to reverse, so it is worth getting right.

When REST is the right choice

REST organises your data as resources (/customers, /orders/123) and uses HTTP methods to act on them: GET to read, POST to create, PUT or PATCH to update, DELETE to remove. It is understood by every developer and tool, it caches well, and it is the safest choice for anything external developers will use. For most business systems it is the right default.

When GraphQL earns its complexity

GraphQL exposes one endpoint where the client asks for exactly the fields it needs. That solves two REST problems: over-fetching (a mobile screen receiving data it does not use) and under-fetching (a dashboard making five calls to build one view). The trade-off is that caching is harder, a single careless query can be very expensive, and authorization must be enforced per field. Use it when you control the clients and their data needs genuinely differ.

When gRPC makes sense

gRPC uses compact binary messages over HTTP/2, which makes it fast and efficient for internal communication between services you own. It is rarely the right choice for a public API. If you are not already running several backend services, you probably do not need it yet.

Design Rules That Keep an API Maintainable

Design the contract before the code

Write an OpenAPI (formerly Swagger) specification first: every endpoint, parameter, response and error. Review it with whoever will consume the API: the mobile developer, the partner, the frontend team. Changing a YAML file costs minutes; changing an API after three apps depend on it costs weeks.

Use resource-based URLs and the right HTTP methods

• Nouns, not verbs: GET /api/v1/invoices, not /api/getInvoices.
• Show relationships through nesting where it helps: /api/v1/customers/42/invoices.
• Use PATCH for partial updates and PUT only when replacing the whole resource.

Be consistent everywhere

Pick one convention and enforce it: snake_case or camelCase field names, ISO 8601 dates in UTC, amounts as integers in the smallest currency unit (cents) with a separate currency field, and the same pagination format on every list endpoint. Consistency is what lets a developer guess correctly how an endpoint they have never used will behave.

Return useful errors

An error response should say what went wrong and what to do about it. Use status codes correctly and keep one error format:

• 400 malformed request, 401 not authenticated, 403 authenticated but not allowed, 404 not found.
• 422 validation failed, with the specific fields and messages.
• 409 conflict (for example a duplicate order), 429 rate limit exceeded with a Retry-After header.
• 500 only for genuine server failures, never with stack traces or SQL in the response.

{
  "message": "The given data was invalid.",
  "errors": {
    "email": ["The email has already been taken."],
    "plan_id": ["The selected plan is not available in your region."]
  }
}

Paginate, filter and sort from the start

List endpoints that return "everything" work in testing and fall over in production. Paginate every list (cursor pagination for large or fast-changing tables), allow filtering on the fields clients actually search by, and cap page sizes.

Versioning Without Breaking Your Clients

Your API will change. The goal is that existing integrations keep working when it does.

• Put the version in the URL (/api/v1/). It is explicit, visible in logs and easy to route.
• Additive changes are safe: new endpoints, new optional fields, new optional parameters.
• Breaking changes need a new version: removing or renaming a field, changing a type, making an optional field required, changing authentication or default behaviour.
• Deprecate with notice: announce a sunset date, send a Deprecation header, and watch logs to see who still calls the old version before removing it.

API Security: The OWASP API Top 10 in Plain English

The OWASP API Security Top 10 (2023) is the industry checklist of how APIs actually get breached. Most items are logic mistakes, not exotic attacks:

1. Broken object level authorization: user A can read user B's record by changing an ID. Scope every lookup to the current user or tenant.
2. Broken authentication: weak token handling, no expiry, no brute-force protection on login.
3. Broken object property level authorization: the API returns or accepts fields it should not, such as is_admin or another user's email. Whitelist fields both ways.
4. Unrestricted resource consumption: no rate limits or page-size caps, so one client can exhaust your server or your SMS budget.
5. Broken function level authorization: normal users can call admin endpoints.
6. Unrestricted access to sensitive business flows: bots abuse sign-ups, coupons or checkout. Add rate limits and abuse checks to business-critical flows.
7. Server-side request forgery (SSRF): the API fetches a URL the user supplied and can be pointed at internal systems.
8. Security misconfiguration: debug mode on, permissive CORS, verbose errors, missing TLS.
9. Improper inventory management: forgotten old versions and test endpoints left running.
10. Unsafe consumption of APIs: trusting data from third-party APIs without validating it.

On top of that: HTTPS everywhere, secrets in environment variables or a secrets manager (never in Git), short-lived access tokens, and logging of authentication failures. I cover application-level security in more depth in web application security, and payment-specific rules in building a secure payment API.

Building an API in Laravel: What It Looks Like

Laravel is my default for business APIs because most of the plumbing above is built in. A few patterns I use on every project:

Authentication with Sanctum

Laravel Sanctum issues API tokens for mobile apps and third parties, and cookie-based sessions for your own single-page app. Tokens can carry abilities, for example read-only, so a reporting integration cannot modify data.

Authorization scoped to the user

// Never: Invoice::findOrFail($id)  — any logged-in user can read any invoice
public function show(Request $request, int $id)
{
    $invoice = $request->user()->invoices()->findOrFail($id);
    $this->authorize('view', $invoice);

    return new InvoiceResource($invoice);
}

Validation with Form Requests

Every input is validated before it reaches business logic, and Laravel returns a consistent 422 response automatically. Only validated fields are used, which closes the mass-assignment hole (OWASP item 3).

API Resources for consistent output

API Resources define exactly which fields leave the server, so adding a column to the database never leaks it to clients by accident.

Rate limiting

RateLimiter::for('api', function (Request $request) {
    return Limit::perMinute(60)->by($request->user()?->id ?: $request->ip());
});

Queues for slow work

Sending emails, generating PDFs or calling slow third-party APIs happen in queued jobs, so the API responds in milliseconds and retries failures automatically. More on structuring Laravel projects in Laravel best practices.

Integrating Third-Party APIs Reliably

Most business systems call several external APIs. These rules prevent the classic failures, such as double charges, lost orders and silent sync gaps:

• Always set timeouts. A third-party outage should slow one feature, not freeze your whole application.
• Retry with backoff, only when safe. Retry network errors and 5xx responses with increasing delays, not validation errors.
• Use idempotency keys for anything that creates money movements or orders, so a retry never charges a customer twice. Stripe and most payment providers support this.
• Prefer webhooks to polling for events such as payment succeeded or shipment delivered. Verify webhook signatures and process them in a queue.
• Store external IDs (Stripe customer ID, Xero invoice ID) next to your own records so you can reconcile and debug.
• Validate what comes back. Treat third-party responses as untrusted input.
• Log every outbound call with a correlation ID so you can trace a customer's problem across systems.

Common integrations I see in business projects: Stripe and PayPal for payments, HubSpot and Salesforce for CRM, Xero and QuickBooks for accounting, Twilio for SMS, SendGrid or Amazon SES for email, and marketplace or shipping-carrier APIs for e-commerce. In the projects I have worked on, such as the WheelsNearMe automotive marketplace, where I was lead developer, the hardest part was rarely the API call itself; it was mapping two systems' different ideas of the same data.

Building Webhooks Your Customers Can Rely On

If your own API sends webhooks to customers or partners, treat them as a product too:

• Sign every payload with an HMAC signature and a timestamp so receivers can verify it came from you and reject replays.
• Retry with backoff for several hours or days when the receiver is down, and show delivery history in the customer's dashboard.
• Include an event ID so receivers can ignore duplicates.
• Keep payloads small and versioned; let receivers fetch full details from the API if they need them.
• Let customers replay events and send a test event while they build their integration.

Typical API Projects for Businesses

Testing an API

• Feature tests for every endpoint: the happy path, validation failures, and, most importantly, a test proving user A cannot access user B's data.
• Contract tests that check responses still match the OpenAPI specification, so a refactor cannot silently break a client.
• Fakes for third-party APIs (Laravel's Http::fake()) so tests are fast and do not hit real services.
• Load tests with k6 or JMeter on the endpoints that matter commercially (search, checkout) before launch, not after.

Documentation Developers Will Actually Use

Generate interactive documentation from your OpenAPI spec (Swagger UI, Redoc or Scribe for Laravel) and add what a spec cannot express: a quick-start guide, authentication steps, example requests in curl and one or two languages, error explanations and a changelog. If partners will integrate, give them a sandbox environment with test data. Good documentation directly reduces support time.

Running an API in Production

• Structured logs with request ID, user, endpoint, status and duration.
• Error tracking (Sentry, Bugsnag, Flare) so exceptions reach you before customers do.
• Uptime and latency monitoring with alerts on error-rate spikes.
• Service level objectives, for example 99.9% of requests under 300 ms, and alerts when you are trending toward breaking them.
• An API gateway (AWS API Gateway, Kong, or Nginx for simpler setups) once you have several services, to centralise TLS, rate limiting and routing.

For speed work beyond the API layer, see web performance optimization.

The API Development Process, Step by Step

1. Discovery (days): list the consumers, the data, the integrations and the business rules. Identify what already exists.
2. Contract (days): write and agree the OpenAPI specification.
3. Foundations: authentication, authorization policies, error format, logging, CI pipeline.
4. Endpoints and integrations in priority order, each with tests.
5. Hardening: rate limits, security review against the OWASP list, load testing.
6. Documentation and sandbox.
7. Launch and monitor, then iterate under versioning rules.

What Drives the Cost of an API

Rather than quote a number that ignores your requirements, here is what actually moves the price:

• Number of resources and business rules: ten simple CRUD resources cost far less than three resources with complex pricing logic.
• Permission model: one user type versus multi-tenant with roles per organisation.
• Number and quality of integrations: a well-documented API like Stripe is quick; an old ERP with SOAP endpoints and no sandbox is not.
• Data migration from a legacy system.
• Public versus private: public APIs need stronger documentation, sandboxes, stricter versioning and abuse protection.
• Compliance: GDPR, HIPAA or PCI requirements add review and logging work.

You can get a rough figure for a full project from my cost calculator, or send me your requirements for a fixed quote.

API Development Checklist

• OpenAPI specification reviewed by the API's consumers
• Version in the URL, and a written deprecation policy
• Every record lookup scoped to the current user or tenant
• Input validation on every endpoint; only whitelisted fields in and out
• Rate limits on all endpoints, stricter on login and sensitive flows
• Consistent error format with correct status codes
• Pagination on every list endpoint
• Timeouts, retries and idempotency on outbound calls
• Webhook signatures verified; webhooks processed in a queue
• Feature tests including cross-user access tests
• Structured logging, error tracking and uptime alerts
• Documentation with quick-start, examples and changelog

Need an API Built or Fixed?

I build and integrate APIs in Laravel and PHP for businesses in the US, UK, Canada, Australia and Europe, working in your business hours. That ranges from a clean REST API for a mobile app to connecting your CRM, accounting and e-commerce systems so data flows without manual work. See API development and API integration, or tell me about your project.