Practical guide

How to connect two systems through an API

First decide who owns the data and when it should change. Only then start writing calls.

25 minutes · System integration

First, the short version

What does connecting systems mean?

An API is an agreement through which applications exchange data. One side publishes an interface and the other calls it by the documented rules. A connection is not a one-off import; it must work during ordinary changes and failures too.

A REST API commonly uses HTTP addresses and methods such as GET or POST. Security does not begin with a URL, though: check who calls, what they may do, and how credentials are protected.

Get ready

What you need before the first connection

Prepare a small, verifiable case first. For example, pass one order, not the whole history.

Official API documentation and a test account or sandbox, if the provider has one.
A description of one event: what triggers it, which data it carries, and what the other system should do.
A decision about which system is the source of truth for every field you pass.
A safe place for tokens and keys: environment variables or a secrets manager, never the repository.

Steps 1 to 3

Build the connection in small parts

A good start is one read or one harmless write. Add further data and two-way changes only after it is verified.

1. Write a small contract

Choose one action, such as “create a customer in the other system”. Write down exactly when it should happen.
List input fields, required values, a successful response, and errors. Agree on time format and identifiers too.
Decide how to recognise the same record in both systems. An internal ID in one system may not make sense in the other.
Start in one direction. Two-way synchronisation creates conflicts and needs separate rules.

Official OpenAPI specification

2. Add a secure API client

Find out how authentication works. It may be an API key, OAuth token, or signed request. Follow the other side’s documentation exactly.
Keep the URL, timeout, headers, and token handling in one client class. A controller or domain logic should not know another service’s technical details.
Check the HTTP status before reading the response. A 401, 404, or 500 is not a valid response with empty data.
Map the response to your own small data shape. A changed field name at the partner will then not spread through the application.

composer require symfony/http-client

Official Symfony HTTP client documentation

3. Handle failures and operation

Set a sensible timeout. Waiting tens of seconds for another system often only blocks your own users.
Log the operation name, internal identifier, HTTP status, and a safe message. Never a full token or extra personal data.
Retry a temporary error only a limited number of times and with a pause. A write that could happen twice needs duplicate protection.
Prepare a way to process a failed delivery again. A user should not have to create the order manually a second time.

Official Symfony documentation on retrying requests

Step 4

Verify the connection with a small sample

Test in a test environment first. During the first production run, watch every delivered case.

Call a simple read

Use an endpoint that changes nothing. It checks the URL, network, and credentials without touching real data.
```
curl -i https://api.example.com/v1/health
```
Send one test record

Compare values on both sides. Check identifiers, dates, currency, empty values, and rounding in particular.
Try a bad token and an outage

The application should log the error clearly, avoid marking data as sent, and offer a safe next attempt.

If something goes wrong

Common problems

The API returns 401 or 403

Authentication and permissions are not the same thing. Check the header format, token validity, and whether the account may use the endpoint.

Data differs after delivery

Keep a sample request and response without secrets. Compare field types, time zones, and rules that turn empty values into zero or the other way around.

An outage in the other system stops your application

Limit waiting and store work that does not have to happen now for later processing. Tell the user clearly what succeeded and what is pending.

The same record is created twice

Use a stable internal identifier or an idempotency key when the API supports it. Before another attempt, check whether the first one really failed.

Done

The connection has a safe foundation.

An API is not only a URL and token. It is an agreement about data, failures, and responsibility. Add further operations one at a time.

Read API in the glossary All guides