API Architectures

Semver

https://semver.org/

x.y.z

#	Name	Description	Spec
x	Major version	Backward incompatible change	8
y	Minor version	New, backward compatible feature	7
z	Patch version	Backward compatible fix of an incorrect behavior	6

OpenAPI

The OpenAPI Specification (OAS), previously known as the Swagger Specification, is a specification for a machine-readable interface definition language for describing, producing, consuming and visualizing web services.

Last known version: 3.2.0 (2025-09-19)

2 possible workflows:

• design-first
• code-first

Example: web service with 1 single GET request of type https://example.fr/bonjour-monde?nom=paul that returns {"message": "bonjour paul"}:

openapi: 3.0.3
info:
  title: Mon Web Service
  version: 0.0.1
servers:
  - url: https://example.fr
paths:
  /bonjour-monde:
    get:
      summary: Génère un message de salutation
      parameters:
        - name: nom
          in: query
          schema:
            type: string
      responses:
        "200":
          description: message de salutation généré
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string

Sources

OpenAPI Specification - Wikipedia