04. Endpoints, data contracts and responses

An interface becomes stable when both sides exchange not just bytes but the same meaning.

The interface as a product

Typical patterns are page-by-page lists, targeted finding, creating and updating. This includes data type, null value meaning, character length, time/currency reference, required fields, status codes and a strategy for compatible changes.

This makes the connection robust

1. Document each use case controller, method, route, request, response and permitted status codes.
2. Define field meaning, unit, time zone, null/blank value and maximum length.
3. Create sample contracts for normal, borderline and error cases.
4. Validate before sending and after receiving.
5. Version mapping and contract together with the client.

Prove production readiness

• Each field has technical meaning and owner.
• Unknown response fields do not break the client.
• Missing mandatory values are recognized before they are called.
• Status codes lead to defined processing.

Mistakes that only become expensive during operation

• An HTTP 200 is equated with technical success without checking the content.
• Date without time zone shifts business days.
• Client binds rigidly to a random sample response.

This is what you take with you

The data flow remains understandable even as versions, fields and error conditions evolve.

Further information / source

Related topics

1. For integration specialists – connect APIs and external systems › 05. Filter, paginate and large amounts of data
2. For integration specialists – connect APIs and external systems › 06. Synchronize items and partners
3. For integration specialists – connecting APIs and external systems › 08. Writing, idempotence and parallelism

Frequently asked questions