Define APIs with OAS

Learning Objectives

After completing this unit, you’ll be able to:

• Explain how the OpenAPI Specification (OAS) provides a blueprint for designing APIs.
  
• Describe how OAS-based design improves consistency, scalability, and collaboration across teams.
  
• Identify key API components such as resources, methods, and parameters.
  

Get Started with Anypoint Code Builder

In the previous unit, you learned how well-structured APIs make integrations scalable, reusable, and easy to maintain. Now, take a closer look at how those principles apply to designing APIs.

The OpenAPI Specification (OAS) is a standardized way to describe APIs before any code is written. It provides a machine-readable format that outlines the resources, methods, parameters, and responses an API supports. With OAS, developers and stakeholders can review the design, provide feedback, and confirm consistency early in the process.

OAS makes it possible to:

• Define API resources, methods, and parameters in a predictable format.
  
• Validate that an API follows best practices before development begins.
  
• Simulate responses to test design accuracy and gather feedback.
  
• Share specifications across teams to improve discovery and reuse.
  

In this unit, you examine how API design fundamentals such as resources, methods, parameters, and reusable components are expressed in OAS. You also learn how these elements work together to support consistent and collaborative API development.

Define Resources

At the core of every API is a set of resources. These are distinct parts of the system that clients can interact with. In OAS, resources are defined using URL paths that describe the type of data or functionality the API exposes.

For example, in a flight booking API, resources might include:

• /flights – A list of all available flights
  
• /flights/{id} – Details about a specific flight
  
• /passengers/{passenger_id}/bookings – Reservations for a passenger
  

Each resource focuses on a specific task or data type. This helps developers find and use exactly what they need.

Tools such as Anypoint Code Builder use OAS to represent resources as part of an API’s structure. After defining resources, you can add methods and parameters that specify how users interact with the API.

Add Methods and Parameters

The first step in API design is to define resources. But to make an API useful, you also need to specify what actions it can perform and how clients can refine those actions. That’s where methods and parameters come in.

In OAS, HTTP methods define how a resource is accessed.

• GET: Retrieves data (for example, get a list of flights).
  
• POST: Creates a new resource (for example, book a flight).
  
• PUT: Updates an existing resource (for example, modify a reservation).
  
• PATCH: Updates part of an existing resource (for example, change just the seat number on a booking).
  
• DELETE: Removes a resource (for example, cancel a booking).
  

To make requests more specific or flexible, APIs use parameters.

• Path parameters help identify a specific resource in the URL path. They’re enclosed in curly braces. For example, in /flights/{id}, the id is a path parameter. These are often required, but in some cases, they may be optional depending on the API design.
  
• Query parameters follow a question mark (?) in the URL and filter or refine the request. Each query parameter uses an equals sign (=) to assign a value, and multiple parameters are separated by an ampersand (&). For example: /flights?departure=JFK&destination=LAX
  

Why Methods and Parameters Matter

Without clear methods and parameters, APIs become difficult to use and maintain. For example, if an API only has a /flights endpoint without query parameters, every request would return all flights instead of just the ones that match a user’s search. Without a DELETE operation, an admin system couldn’t remove outdated or canceled flights from the airline’s schedule.

Well-defined methods and parameters make APIs more intuitive, efficient, and flexible. They allow applications to retrieve the right data quickly while keeping API requests lightweight and performant.

Design for Reuse

An API should be built to last. If every new feature requires major changes or if different teams have to create separate APIs for similar tasks, things get messy fast. A reusable API design avoids these problems by staying flexible enough to handle future updates without breaking existing integrations.

Reusability reduces maintenance, speeds up development, and makes integrations more scalable.

Best Practices for Reusable APIs

To design APIs that remain useful as business needs evolve, follow these best practices.

• Use consistent naming conventions. A predictable structure makes APIs easier to understand and navigate. If one endpoint is /getFlightInfo and another is /bookings/{id}, developers have to guess the pattern instead of following a clear, logical format.
  
• Standardize data structures and patterns. Use consistent field names and response formats for things like passenger details, authentication, and error handling. This helps teams build integrations faster and maintain them over time.
  
• Version APIs properly. Changes are inevitable, but they shouldn’t break existing integrations. Versioning (/v1/flights, /v2/flights) lets different versions coexist, giving consumers time to migrate.
  
• Document API behaviors clearly. A well-documented API helps developers integrate faster and prevents misunderstandings that could lead to costly rework or errors.
  

These guidelines allow an API to adapt to changing needs without forcing developers to constantly rewrite integrations.

Mule United Airport Builds a Scalability API

At Mule United Airport, multiple groups—each with different needs—rely on the flight booking API.

• Passengers search for flights by date and departure city and book tickets.
  
• Airline staff update flight schedules and check seat availability.
  
• Operations teams monitor real-time flight status and gate assignments.
  

A well-structured API with clear methods and parameters provides each team only the data they need and doesn’t overload the system with unnecessary requests.

Instead of building separate APIs for each team, MUA designs a single, flexible API that supports multiple use cases. This modular approach lets new features—like baggage tracking or loyalty program integration—be added without disruption to existing functionality.

Since the team at MUA started with a properly structured API, they avoid duplicate work, reduce maintenance overhead, and support future scalability.

Wrap It Up

Now you know the key elements of API design using OAS, including how to define resources, add methods and parameters, and improve clarity with examples and consistent design patterns.

Tools like Anypoint Code Builder support these principles with an environment to structure and organize APIs effectively.

In the next unit, you review a complete API specification. You also explore how its structure supports mocking and stakeholder review without requiring hands-on access to development tools.