Explore a Mock-Ready API
Learning Objectives
After completing this unit, you’ll be able to:
- Recognize the elements of a complete API definition in the OpenAPI Specification (OAS).
- Explain how query parameters and response examples make an API easier to test and review.
- Explain how an API structure supports mocking and early stakeholder feedback.
- Describe how APIs are prepared for testing and stakeholder review.
Design with Purpose
You explored what makes a great API: clearly defined resources, reusable structures, and predictable behaviors. Now, it’s time to look more closely at how these elements come together in a complete API design.
Don’t worry, you’re not jumping into backend logic or live deployment. Instead, the focus here is on spec-first design, a best practice that defines how an API should behave before implementation.
Why is that helpful?
Because designing your API first means:
- You can validate the structure early.
- Other teams can review and give feedback.
- You can mock and test behavior before writing a single line of backend code.
In this unit, you review a guided example of a fully structured API definition created with the OpenAPI Specification (OAS). You also discover how design choices made at this stage prepare the API for testing and stakeholder review in the next step of the journey.
Mule United Airport Designs Its Flights API
At Mule United Airport, the API team designs a new endpoint to help internal and partner teams find available flights. This early version of the API is defined using OAS so that it can be reviewed, tested, and mocked before any backend code is written.
How the API Is Defined
Here’s the structure of the API definition.
- Base path and resource:
/flightsrepresents the endpoint where flight data is requested. - HTTP method: A
GETmethod retrieves a list of flights. - Query parameter: A parameter named
destinationallows filtering by city code. - Response example: A sample JSON payload shows the data structure returned by the API.
Sample Specification (YAML)
# OpenAPI specification version
openapi: 3.0.0
info:
# Metadata about the API
title: American Flights API
version: 1.0.0
paths:
/flights:
get:
# Summary of what this operation does
summary: Retrieve a list of flights
# List of inputs that can be passed to the API operation
parameters:
- in: query # Specifies that the parameter is passed in the query string of the URL
name: destination # The name of the query parameter (e.g., /flights?destination=SFO)
schema:
type: string # The expected data type of the parameter
description: Filter flights by destination
responses:
'200':
# Description of the response
description: A list of flights
content:
application/json:
# Sample JSON response body
example:
- flightNumber: AA123
destination: SFO
Design for Errors
An API definition is not complete if it only describes the successful path. Consumers also need to know what happens when something goes wrong. API design should include standardized error responses so developers can anticipate and handle issues consistently.
For example, the American Flights API might include these responses.
'400':
description: Invalid request
content:
application/json:
example:
error: "Bad Request"
message: "The destination code is missing or invalid"
'404':
description: Flight not found
content:
application/json:
example:
error: "Not Found"
message: "No flights match the request"
'500':
description: Internal server error
content:
application/json:
example:
error: "Server Error"
message: "An unexpected error occurred. Please try again later."An API definition that shows both the success response and the error cases:
- Sets clear expectations for developers
- Uses common scenarios to make testing realistic
- Encourages consistency across teams and endpoints
When error handling is included in the design phase, it reduces surprises during development and improves collaboration between API producers and consumers.
Learn How Tools Help
In tools like Anypoint Code Builder, editors provide syntax highlighting, auto-completion, and real-time validation to help catch errors. API console previews can also render the spec into a testable view for stakeholders.
Use a Checklist for a Mock-Ready API
A complete API definition includes all the details that make it testable and easy to review. Use this checklist to confirm the essentials are in place.
- Resources and endpoints clearly defined
- Methods attached to each resource to describe allowed actions
- Parameters included to filter or refine requests
- Example responses show expected data structure
- Error responses describe what happens when something goes wrong
- Consistent naming conventions and standardized formatting keep the design predictable
When these elements are present—before the backend code is written—the API is clear, easy to test, and ready for mocking, stakeholder review, and early feedback.
Wrap It Up
When you design APIs before implementation, teams can collaborate early, catch issues before they escalate, and stay aligned on expected API behavior.
In the next unit, you learn how a mock-ready API can be tested and reviewed using sample requests and responses. This approach lets stakeholders provide feedback to confirm the design is solid before any backend code is written.