An API is often described as a bridge between systems. That is useful, but incomplete. A bridge also needs traffic rules, maintenance, and a plan for what happens when one side is closed.
For a business, the real question is whether information reaches the right place, with the right permission, once and only once, and whether failed work can be found and recovered.
Describe the Business Conversation First
Suppose a website sends a new enquiry to a CRM. The technical task sounds simple, but several business questions come first. When is the enquiry considered complete? Which system owns the customer record? What happens if the email address already exists? Who receives an enquiry outside business hours? Can the CRM reject a record because a required field is missing?
Write the flow in ordinary language before designing endpoints. Name the event, required information, owner, expected response, and failure action. This prevents an integration that transfers data correctly but does not support the way people work.
Avoid making the public API a direct copy of database tables. A database is organised for storage and can change as the application evolves. An API should present stable, understandable resources and actions such as customers, orders, approvals, or subscriptions.
Agree on the Contract
The contract defines the address, method, fields, accepted values, response, and errors for every request. Use consistent names and formats. Mark which fields are required, which can be empty, and which values are controlled lists. Include examples of successful and unsuccessful requests.
OpenAPI is a widely used way to describe HTTP APIs in a form people and tools can read. It can support documentation, testing, and generated client code, but the written description still needs business meaning. A field named status is not useful if nobody knows the allowed states or who can change them.
Decide how change will be handled before other systems depend on the API. Compatible additions may not need a new version, while removed fields or changed meaning can break clients. Keep an inventory of consumers, publish a retirement plan, and allow enough time for owners to update.
Separate Identity From Permission
Authentication answers who or what is calling. Authorization answers whether that caller may perform this action on this specific record. A logged in customer should not be able to change another customer's order by guessing its identifier. An internal service should receive only the permissions it needs.
OWASP lists broken object authorization, broken authentication, resource consumption, and unsafe use of other APIs among important API risks. Translate that into design work: deny access by default, check permission on every object and action, validate input, limit abusive traffic, protect secrets, update dependencies, and avoid returning fields the caller does not need.
Logs should help investigate a problem without collecting passwords, access tokens, payment card data, or unnecessary personal information. Define retention and access for logs just as carefully as the main database.
Compare the Options
Swipe sideways to compare every column.
| Decision | Useful question | Failure it prevents |
|---|---|---|
| Data ownership | Which system may make the final change to this field? | Conflicting customer or order records |
| Authorization | Can this caller perform this action on this exact record? | Exposure or alteration of another user's data |
| Retry design | What happens if the same request arrives twice? | Duplicate orders, messages, or payments |
| Version change | Which consumers will break if this meaning changes? | Unexpected failure after an API release |
| Monitoring | How will operations find and replay failed work? | Silent loss between otherwise healthy systems |
Design for Failure, Duplicates, and Delay
Networks fail. A CRM may be slow, a payment provider may send the same webhook more than once, or a client may retry after losing the response. The integration must know whether repeating a request is safe.
For actions such as creating an order or charging a payment, use an idempotency key or another reliable duplicate control. Store enough information to recognise a repeated request. For webhooks, verify the sender according to the provider's current documentation, return a response promptly, process longer work safely, and record the event before acknowledging it when appropriate.
Retries should use limits and increasing delays rather than hitting a struggling service continuously. After the limit, place the item in a visible failure queue and alert the owner. A person should be able to replay the work after the cause is fixed without creating a second business record.
Make the Integration Operable
A green server light does not prove that leads reached sales or orders reached fulfilment. Monitor business outcomes as well as technical responses. Count records received, accepted, rejected, delayed, retried, and sent for manual review. Use a shared reference so a support person can trace one customer event across systems.
Write a short operating guide. It should explain the data owner, normal delay, common errors, replay process, contact for each connected system, and action during an outage. Test that guide before launch by disconnecting a dependency or sending an invalid record in a safe environment.
- Health and latency by connected service
- Failed, delayed, retried, and duplicate events
- Business records created in each system
- Permission denials and unusual traffic
- Versions and consumers still in active use
Deliver One Complete Flow Before Adding More
Begin with one business flow and take it through documentation, security review, testing, monitoring, and recovery. A small complete integration is more valuable than many endpoints nobody knows how to operate.
Test normal requests, missing fields, invalid values, duplicate delivery, slow dependencies, expired credentials, permission failures, and partial outages. Include the people who use the result. They often find workflow problems that endpoint tests cannot see.
Practical Checklist
Before development
- Map the business event and name the owner of each field
- List every system that sends or receives information
- Define authentication, authorization, and secret management
- Agree request, response, error, duplicate, and retry behaviour
- Identify personal or sensitive data that can be removed
Before launch
- Test access using several roles and record owners
- Send duplicate and out of order events
- Simulate a slow or unavailable dependency
- Confirm alerts lead to a named person and recovery action
- Publish documentation and a change policy for consumers
Related Technical Support
API Development
API development and integrations for CRMs, apps, ecommerce, payments, dashboards, and workflow automation.
Closing Advice
A good API is a dependable agreement between systems and teams. It states what an action means, protects each record, handles failure without duplication, and makes missing work visible.
If you are planning an integration, choose one important business event and design the whole journey from request to recovery before adding more endpoints.
Sources and Further Reading
- OWASP API Security Top 10 2023. A current awareness guide to common API security risks.
- OpenAPI Specification. The official specification for describing HTTP APIs.
Editorial note: Security requirements depend on the data, users, connected providers, and operating environment. A qualified review is appropriate for sensitive or regulated systems.