%% date:: [[2023-04-11]], [[2023-07-14]] parent:: %% # [[OpenAPI]] OpenAPI is a set of standards for how to implement [[API]]s to facilitate their use. OpenAPI was formerly known as the [[Swagger]] specification, and the terms are still used interchangeably, but Swagger is actually the name of the company that developed it, not the protocol itself. Typically, in order to use a [[REST]]ful API, the API's endpoints and expected formats must be documented. However, if the API contains an OpenAPI description of the endpoints, then the description is machine-parseable and would not require a human to read it. The OpenAPI specification is often seen as an alternative to [[HTTP]] APIs and are language-agnostic. ## OpenAPI Document An OpenAPI document is a type of contract that defines the syntax and structure of the API. It is a [[JSON]] or [[YAML]] file that defines objects like paths, components, or webhooks. ## Anatomy of an OpenAPI request To make an OpenAPI request, you need a path template, parameter values, and a call that puts the two together. The **path template** can be defined in [[YAML]] like this: ```yaml paths: /pets/{petId}: get: operationId: getPetById parameters: - name: petId in: path required: true description: The id of the pet to retrieve schema: type: string ``` [^google] The path template shows how the relative URL maps to a specific *operation*. An operation ## OpenAPI and [[Remote Procedure Call|RPC]] OpenAPI can be thought of [^google] as a type of procedure-oriented API that makes a [[Remote Procedure Call]], but then adds custom mappings of those procedures to [[HTTP]]. While OpenAPI's use of [[HTTP]] as a transport protocol can cause it to be categorized as an entity-oriented API model, the fact that it uses a URL path template instead of the asset itself makes it similar to how [[Remote Procedure Call|RPC]] works. ## Benefits of OpenAPI - Minimizes time and effort - Tools can be used to convert definitions into code - Documentation can be automatically generated from the API definition - Interactive documentation allows devs to test operations - OpenAPI is great for continuous testing, because functional and nonfunctional tests can easily be created from modified endpoints. ## Resources ### How to use [[Portman]] to generate tests from an OpenAPI spec <iframe width="560" height="315" src="https://www.youtube.com/embed/Be66Db4wHLA?start=2930" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe> [^google]: Nally, M. (2020). *gRPC vs REST: Understanding gRPC, OpenAPI and REST and when to use them in API design.* Retrieved on July 13th, 2023 from https://cloud.google.com/blog/products/api-management/understanding-grpc-openapi-and-rest-and-when-to-use-them