Understanding APIs and Systems Integration: A Practical Introduction

An API is an agreed interface through which software can request information or actions from another system. It lets a customer portal check an order without reading the order database directly, for example. The interface defines what can be requested, how to request it and what a response means.

Integration is the wider work of making that exchange useful and dependable. It includes ownership, mapping fields, permissions, error handling and operating support.

Requests, responses and REST

Many web APIs exchange HTTP requests and responses. REST is an architectural style often reflected in resource-oriented URLs and standard HTTP methods. APIs described as REST vary, so always read their actual contract. A GET usually retrieves a representation; creating a resource often uses POST.

Here is an illustrative request to a fictional endpoint. It does not connect to a TEYSYS service:

GET /v1/orders/ORD-1042 HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN

A successful response might return status 200 and this JSON body:

{
  "id": "ORD-1042",
  "status": "ready",
  "total": { "amount": "240.00", "currency": "GHS" }
}

JSON represents structured values: objects, arrays, strings, numbers, booleans and null. This example deliberately carries currency beside the amount and uses a decimal string; real APIs may choose another money representation. Match the documented schema rather than assuming a number always means the same unit. Explore sample responses locally with the API Response Viewer.

Authentication is only one part of access control

An API key or access token can identify an authorised client. The server must also check what that client may do and which records it may access. A valid token is not permission to retrieve every customer order.

Use HTTPS, keep credentials out of source control and URLs, and give integrations only the permissions they need. Secrets used by trusted server processes should not be embedded in public browser code. Plan rotation and revocation. Reading a JWT payload with an inspector does not verify its signature or establish trust.

Webhooks deliver events

Instead of repeatedly asking whether an order changed, a system can send a webhook when an event occurs. A receiving endpoint validates the provider's authentication or signature scheme, checks the event type and records a delivery identifier before processing it.

Design for duplicates and delay. Providers may retry failed deliveries, and some contracts do not guarantee event order. A payment handler should not create a second receipt just because the same event arrives again. Follow the provider's response-time requirements and move lengthy work to a controlled background process where appropriate.

Make failures part of the design

Common problems include mismatched identifiers, changing schemas, missing fields, rate limits and timeouts. A timeout does not prove an action failed: the remote system may have completed it before the connection ended. Use the provider's idempotency mechanism when available and reconcile uncertain outcomes before repeating financial or irreversible actions.

Validate input at boundaries, define retry limits and preserve enough diagnostic information to investigate a failure without logging tokens or unnecessary personal data. Decide who receives alerts and who can correct a stuck record.

A business example: paid orders to fulfilment

Agree that the payment service owns payment confirmation and the order application owns dispatch status. Map the payment reference to an order identifier. Verify event authenticity, reject inconsistent amounts and route unmatched payments for human review. Only eligible, confirmed orders enter fulfilment. Reconcile periodically so missed events can be found.

Before implementation, document the fields, ownership, permission scope, failure paths and support responsibilities. TEYSYS's Systems Architecture & Integration service helps define those boundaries.

For technical background, read MDN's HTTP overview and GitHub's webhook practices; provider-specific requirements remain authoritative for each integration.