API development and integration: connecting your business systems

What is an API, and why does its design matter?

An application programming interface, or API, defines how one piece of software can interact with another. A useful analogy is a restaurant menu: the customer can request a defined service without knowing every detail of how it is delivered.

In business software, that might mean sending orders to an ERP system, exchanging customer records with a CRM or connecting an online store to a payment provider. The API establishes the operations, data and rules involved in that exchange.

A well-designed interface can reduce manual work and make new integrations easier to add. A poorly understood interface can instead become a source of missing data, duplicate actions and recurring support work. Treat the integration as a business workflow with failure states, not simply a connection between two URLs.

REST, GraphQL and SOAP: choosing an approach

The right approach depends on the systems involved and the needs of their consumers. Existing third-party software may already determine which interface you must use.

• REST: an architectural style commonly used for HTTP APIs. Resource URLs, HTTP methods and status codes can provide a familiar interface for web applications and integrations.
• GraphQL: lets a client specify the fields it needs through a typed schema. It can suit applications with different data requirements across screens or clients.
• SOAP: a messaging protocol used in some enterprise and legacy integrations, typically with XML messages and a defined service contract.

A familiar HTTP API is often a practical starting point. GraphQL can be useful when clients need flexible access to related data, but it does not remove the need for authorization, performance controls or careful backend implementation. The official GraphQL introduction explains its query and schema model.

How an HTTP API is organized

An API endpoint identifies an operation or resource. For example, /api/users/123 can identify a user, while /api/users/123/orders can identify that user's orders.

• Methods express the intended operation: reading, creating, replacing, updating or deleting data.
• Status codes communicate outcomes such as a successful response, a missing resource or an error.
• Payloads carry the data, often as JSON, with documented field names and types.

The design should be consistent enough that another developer can predict how similar operations behave. For example, a documented resource route such as /api/v1/users/123/orders makes the relationship clearer than a collection of unrelated script names. Naming alone does not make an API reliable; its behavior must match the contract.

When GraphQL can help

Different clients may need different views of the same records. A mobile screen might need only a name and status, while an internal dashboard needs several related details. GraphQL allows each client to request the fields it needs.

This can reduce unnecessary data transfer or extra requests in suitable cases. It is not an automatic performance improvement: query complexity, data access and caching still need attention. Decide from the actual workflows and the team's ability to operate the result.

The stages of an API project

1. Discovery and interface design. Identify the systems, data owners, operations, permissions and business outcomes. Agree what should happen when a dependency is unavailable.
2. Implementation. Build the endpoints and processing logic in a separate environment. Keep test credentials and data separate from production.
3. Testing. Check successful requests, validation failures, permissions, duplicates, timeouts and representative workloads.
4. Documentation. Describe the contract alongside the implementation, including examples and error responses.
5. Deployment and monitoring. Plan access, secrets, release steps and the signals that will reveal a failed integration.
6. Maintenance. Assign responsibility for dependency updates, external API changes and future modifications.

These stages are part of the scope to agree with your supplier. Monitoring coverage, response times and ongoing support should be explicit rather than assumed to be included in every development project.

Architecture that supports change

Good interface boundaries help you add a new consumer or replace a connected system without rewriting every workflow. Decide which application owns each type of data and which operations are allowed to change it.

You do not need microservices simply because you need an API. A well-structured single application may be easier to develop and operate. Separate services can be useful where there is a clear reason for independent delivery or scaling, but they also introduce network failures, coordination and monitoring work.

Assess those tradeoffs against the system's current needs. The goal is an architecture the team can understand, test and maintain.

Security questions to include in the specification

• Authentication: how will the API identify the client or user? How will credentials be issued, stored, rotated and revoked?
• Authorization: which records and actions may that identity access? A valid login must not imply access to every customer's data.
• Transport protection: use HTTPS for communication and handle secrets outside URLs and ordinary application logs.
• Request limits: define appropriate limits and how clients should respond when they are reached.
• Input and output handling: validate expected data and apply the relevant protections in database queries and rendered output.

Authentication and authorization are different responsibilities. Laravel's authorization documentation describes gates and policies for deciding whether a user may perform an action. A framework provides mechanisms; project-specific rules and tests are still necessary.

Integrating with third-party systems

Connecting to an accounting tool, CRM, payment provider or logistics service involves constraints you do not control. Review the external documentation before estimating the integration.

• Documentation gaps: verify unclear behavior in an appropriate test environment.
• Rate limits and quotas: understand the provider's limits and expected response to excess requests.
• Failures: define timeouts, retry behavior and what users see when work cannot complete.
• Repeated messages: prevent a retried request or event from accidentally creating the same business action twice.
• Observability: record enough information to investigate failures without exposing credentials or unnecessary personal data.

A successful integration needs an operational owner. Someone must be able to notice a failed synchronization, understand its impact and recover it safely.

Documentation, versioning and asynchronous work

Useful documentation includes endpoints, parameters, data types, permissions, examples and error responses. The OpenAPI specification provides a standard description format for HTTP APIs and can support documentation and other tooling.

When behavior changes, consider the consumers already using it. A versioning and deprecation policy gives them time to adapt. Version numbers alone are insufficient: document what changed and when old behavior will stop being supported.

Some work finishes after the initial request. An API may acknowledge the request and later provide a result through polling or an event such as a webhook. Document the status lifecycle, delivery expectations and handling of repeated or out-of-order events.

Common questions

What determines the cost of an API?

The number of endpoints is only one factor. Business rules, permissions, external dependencies, data mapping, failure handling, testing and documentation can dominate the work. A useful estimate starts with the workflows and the interfaces that already exist.

How is an SDK different from an API?

An API defines an interface. An SDK is a collection of tools or libraries that helps developers use a platform, often including a convenient wrapper around its API. A web service exposes functionality through web protocols.

Do we need an API gateway?

A gateway can provide a common entry point for routing and selected cross-cutting controls. Whether you need one depends on the architecture and operating requirements. It does not replace the authorization rules inside your applications.

Why does devBoys use Laravel for API work?

Laravel fits our PHP application development stack and provides established tools for routing, data access, authorization and testing. We choose the implementation around the project's constraints and the systems it must connect.

Need to connect your business systems or expose data to partners? Explore our custom application development or describe the integration you need.