REST OpenAPI — Cheat Sheet

Tag: rest, openapi, swagger, api, backend, http, json

Livello: intermedio

TL;DR: Principi REST, standard OpenAPI/Swagger per documentazione, design contract-first e gestione di status code e metodi HTTP.

Concetti chiave

REST e architettura basata su risorse identificate univocamente tramite URI.

Interfaccia uniforme basata sui metodi HTTP standard: GET, POST, PUT, PATCH, DELETE.

Stateless: ogni richiesta dal client al server contiene tutte le informazioni necessarie.

Cacheability: risposte esplicitamente marcate come memorizzabili in cache o meno.

Idempotenza: GET, PUT, DELETE producono lo stesso stato se eseguiti ripetutamente; POST no.

PATCH applica modifiche parziali; PUT rimpiazza l'intera risorsa.

OpenAPI Specification definisce un formato standard neutrale per descrivere API RESTful.

Approccio Contract-First: definizione dello schema YAML/JSON prima dell'implementazione.

Componenti chiave OpenAPI: paths, operations, parameters, requestBody, responses e components.

Versionamento API gestibile tramite URI path, header personalizzati o parametri di query.

Domande tipiche e risposte pronte

Q: Qual e la differenza sostanziale tra i metodi HTTP PUT e PATCH?R: PUT sostituisce completamente la risorsa con il payload fornito ed e idempotente, mentre PATCH applica aggiornamenti parziali ai campi specificati.

Q: Cosa significa approccio Contract-First e perche preferirlo rispetto al Code-First?R: Definisco prima la specifica OpenAPI con i contratti di interfaccia, permettendo a frontend e backend di lavorare in parallelo con mock server.

Q: Quando e corretto utilizzare il codice di stato HTTP 201 rispetto a 200?R: Uso 201 Created quando una richiesta POST genera una nuova risorsa, includendo l'header Location con l'URI della risorsa creata.

Q: In cosa differiscono 401 Unauthorized e 403 Forbidden?R: Il 401 indica che l'utente non e autenticato, mentre il 403 indica che l'identita e nota ma mancano i permessi per accedere alla risorsa.

Insidie e errori comuni

Uso di verbi negli endpoint invece di sostantivi per le risorse.

Violazione dell'idempotenza implementando effetti collaterali su chiamate GET.

Ritornare codice 200 OK con payload contenente dettagli di errore applicativo.

Confusione tra codici di risposta 401 per autenticazione e 403 per autorizzazione.

Disallineamento tra il contratto OpenAPI e l'implementazione reale del server.

Snippet e comandiYAML

```openapi: 3.0.3

info:

title: Items API

version: 1.0.0

paths:

/items/{id}:

get:

summary: Get item by ID

parameters:

• name: id

in: path

required: true

schema:

type: string

responses:

'200':

description: Item trovato

content:

application/json:

schema:

$ref: '#/components/schemas/Item'

'404':

description: Item non trovato

components:

schemas:

Item:

type: object

properties:

id:

type: string

name:

type: string

required:

• id
• name

```

Da ripassare

[ ] Gestione HATEOAS e livelli del Richardson Maturity Model

[ ] Differenze strutturali tra OpenAPI 3.0 e OpenAPI 3.1

[ ] Configurazione di Swagger UI e generazione automatica dei client SDK

[x] Semantica dei metodi HTTP e mapping degli status code principali