OpenAPI
Introduction to APIs
API stands for Application Programming Interface.
It is a set of rules and tools that allows one software application to interact with another.
APIs are essential for enabling the integration and communication between different software systems,
allowing them to share data, services, and functionalities.
Types of APIs:
1. Web APIs: These are APIs accessed over the internet using HTTP/HTTPS protocols. Examples include RESTful
APIs and SOAP APIs.
a. REST (Representational State Transfer) is a common architecture for building web APIs. It uses
standard HTTP methods (GET, POST, PUT, DELETE) to perform actions.
2. Library APIs: These are APIs provided by software libraries or frameworks that allow developers to use pre-
built functions or methods.
3. Operating System APIs: These are APIs that allow applications to interact with the operating system, such as
file handling or memory management.
OpenAPI
- OpenAPI is a specification that defines a standard way to describe RESTful APIs.
- It is language-agnostic, meaning it can be used to describe APIs implemented in any programming language.
- The OpenAPI Specification (OAS) provides a structured way to define all aspects of your API, including
endpoints, request parameters, response formats, security mechanisms, and more.
Key Concepts of OpenAPI:
1. Specification Document: → Typically in JSON or YAML format
2. Paths and Operations: → URI where API is accessible
3. Parameters → sent to API
4. Responses
5. Schemas → format for data sending to API
6. Security → OAuth and tokens for API
7. Documentation → auto generation of docs by swagger UI
8. Versioning
Tools Supporting OpenAPI:
1. Swagger UI: For generating interactive documentation.
2. Swagger Editor: An online editor to write and visualize OpenAPI documents.
3. Postman: Import OpenAPI documents to define and test APIs.
4. Code Generators: Generate server stubs, client SDKs, and more from OpenAPI definitions.
Swagger v/s OpenAPI :
OpenAPI: The specification that standardizes how APIs are described.
Swagger: The suite of tools (including Swagger Editor, Swagger UI, etc.) that help in working with APIs, particularly
those described using the OpenAPI Specification.
2015 SmartBear donated Specifications to OpenAPI Linux Foundation.
Approaches to create OpenAPI spec
1. Code first Approach → create API first then specs
2. Design first Approach → create specs first then AP
2. Design first Approach:
In this approach, the API's design is created before any code is written. The OpenAPI specification is developed
first, which serves as the blueprint for implementation.
Why Design-First?
Clarity: The design-first approach provides a clear understanding of the API's structure, making it easier for
stakeholders to provide feedback before any code is written.
Collaboration: Teams can collaborate on the API design, ensuring that all requirements are met and reducing the
likelihood of miscommunication.
Consistency: It ensures consistency across different teams and projects, as everyone follows the same design.
API Mocking: Tools like SwaggerHub allow you to mock the API based on the design, enabling frontend and backend
teams to work in parallel.
Key Components of OpenAPI:
Paths: Defines the endpoints of your API.
Operations: Describes the HTTP methods (GET, POST, PUT, DELETE, etc.) for each endpoint.
Parameters: Specifies the inputs required for the API (query parameters, path parameters, headers, etc.).
Request Bodies: Defines the structure of data expected in the request.
Responses: Details the possible responses (status codes, response bodies) the API can return.
Security: Describes the authentication methods used by the API.
Tags: Organizes the endpoints into logical groups.
openapi: 3.0.3
info:
title: Bookstore API
description: A simple API for managing a list of
books.
version: 1.0.0
paths:
/books:
get:
summary: Get a list of all books
description: Retrieve a list of books
tags:
- Books
responses:
'200':
description: A list of books.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Book'
'500':
description: Server error
Adding Security in OpenAPI
OpenAPI in Spring boot project