Interoperability enables different systems and applications to exchange data and work together efficiently without complex processing or coding. In API design, it depends on consistent, standard data, operations, and flows that consumers can understand and reuse. section 8.1 section 8.2.5
Design for interoperability by making each API surface predictable and reusable:
- Use clear, consistent names and representations across resource paths, models, parameters, request bodies, responses, and errors. section 8.2 section 8.3.1
- Prefer well-known domain-specific or generic standards over locally invented formats, while recognizing that standards can sometimes reduce user-friendliness. section 8.2.5 section 8.4.5
- Apply interoperability in a deliberate second pass after establishing versatile data and operations, revisiting the design as questions arise. section 8.3.2 section 9.2.1
- Keep identifiers, inputs, outputs, errors, and operation behavior consistent so data from one operation can serve another. section 8.2.5 section 9.2.2
Standardizing a location
A local location object might use latitude, longitude, and address consistently. A more broadly interoperable representation uses GeoJSON: {"type":"Point","coordinates":[12,34]}. The standard simplifies sharing and interpretation, even though the coordinate array may be less intuitive for users. section 8.2.5
Making an operation predictable
A messaging API becomes easier to integrate when it uses POST /messages and returns 400 Bad Request with {"error":"Missing phone number"}. Consistent HTTP methods and actionable errors let clients handle failures without special processing. section 8.1.3 section 9.1.3
Figure 3.4 Some web APIs don’t respect HTTP semantics. Their creator may wrongly call them “REST” simply because they use HTTP.
Compare an HTTP-compliant DELETE /products/123 with a noncompliant GET /deleteProduct/123 to see how standard method and status semantics support interoperability. section 3.1.3
