Jakie typy umów są stosowane przy tworzeniu API REST?

Podczas tworzenia REST API stosuje się następujące typy kontraktów:

• OpenAPI (Swagger) — standard do opisywania REST API, umożliwiający dokumentację i generowanie kodu klienta.
• JSON Schema — określa strukturę obiektów JSON używanych w żądaniach i odpowiedziach.
• gRPC (chociaż nie jest to REST, czasami jest używany jako kontrakt dla API) — protokół z kontraktem opartym na protobuf.

W kontekście REST API najczęściej używa się OpenAPI, które opisuje:

• Punkty końcowe (ścieżki i metody HTTP)
• Format żądań i odpowiedzi
• Parametry i nagłówki
• Kody odpowiedzi

Przykład prostego fragmentu OpenAPI:

paths:
  /users:
    get:
      summary: Pobierz listę użytkowników
      responses:
        '200':
          description: Udana odpowiedź
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'