OpenAPI
OpenAPI describes HTTP interfaces in machine-readable form, including paths, parameters and responses. The description must match the running service.
Recording an understandable HTTP API contract
OpenAPI is a standard for describing HTTP APIs. An OpenAPI description records the paths, operations, parameters and response structures offered, among other details. It can be represented as JSON or YAML. The description language does not depend on the programming language used to build the service.
A fictional software company plans GET /projects/{projectId} for its project portal. The description is to define projectId as a path parameter; the successful 200 response is to include the text field name among other fields. Known error responses also belong in the contract. The path and fields are our own design examples, not a complete OpenAPI document or an existing service.
The frontend team can use this to understand what information to send and which responses to handle. The file alone does not show whether the running implementation follows that contract. Before handover, the description and actual responses, including error cases, would need to be compared. The meaning of name must also be agreed: a correctly typed string does not explain which name the field contains.
Sources
Related terms
- APIAn API defines how software can use functions or data offered by other software.
- RESTREST defines architectural constraints for distributed interfaces. Resources, stateless requests and links are part of the approach.
- Server-sent eventsServer-sent events carry text notifications from server to client over HTTP, for example about the progress of a background job.
- Entity tagAn ETag identifies a particular representation version of an HTTP resource and supports conditional reads or changes.
- Cross-Origin Resource SharingCORS controls browser access to responses across origin boundaries. It replaces neither API login nor permission checks.
- Electronic Data InterchangeEDI transfers structured business documents between systems. Format, partner profile, data mapping and responses need to agree.
Your project with ASES
Describe your project to us. We will get back to you with an initial assessment.