API FRD: funkcionalni zahtevi za API proizvode

API FRD opisuje ponašanje sistema čiji je primarni interfejs API — REST, GraphQL, gRPC ili na bazi webhook-ova. Umesto ekranskih scenarija i UI interakcija, on definiše endpoint-e, šeme zahteva i odgovora, metode autentifikacije, kodove grešaka i ograničenja brzine zahteva.

Dokument obavlja isti zadatak kao standardni FRD: daje programerima i QA-u tačnu specifikaciju ponašanja sistema. Razlika je u opsegu — API FRD se fokusira na ugovor između sistema, a ne na ugovor između sistema i čoveka.

Key insight

API FRD je specifikacija na koju se oslanjaju potrošači API-ja. Ako FRD kaže da odgovor 404 sadrži polje error_code, svaki API klijent će pisati kod prema tom ugovoru. Promeniti ga kasnije znači pokvariti integracije.

Kada koristiti API FRD

Koristite API FRD kada:

• Gradite javni ili partnerski API sa kojim će se integrisati eksterni programeri
• Sistem je mikroservis koji komunicira sa drugim internim servisima putem API-ja
• Više timova treba zajednički ugovor da bi mogli da grade paralelno
• API služi kao backend za mobilnu aplikaciju, SPA ili integraciju sa trećom stranom

Standardni FRD je bolji izbor kada:

• Sistem ima značajan korisnički interfejs pored API-ja
• Poslovna pravila i radni procesi su važniji od specifikacija endpoint-a
• Publika dokumenta su poslovni analitičari, a ne backend inženjeri

Sekcije API FRD-a

1. Pregled API-ja

Kratak opis šta API radi, ko ga koristi i kako se uklapa u širi sistem. Uključuje:

• Naziv i verziju API-ja
• Bazni URL (production, staging)
• Metod autentifikacije (API key, OAuth 2.0, JWT)
• Transportni protokol (HTTPS, gRPC)
• Format podataka (JSON, Protocol Buffers)

2. Autentifikacija i autorizacija

Tačan opis kako se klijenti autentifikuju i koji model autorizacije API koristi.

Uključite opis šta se dešava kada autentifikacija ne uspe: format tela odgovora HTTP 401, kodovi grešaka i prisustvo Retry-After header-a.

3. Endpoint-i

Srce API FRD-a. Svaki endpoint dobija zasebnu podsekciju:

Format specifikacije endpoint-a:

Primer: endpoint za kreiranje narudžbine

POST /api/v1/orders

Request body:
{
  "customer_id": "string (required, UUID)",
  "items": [
    {
      "product_id": "string (required, UUID)",
      "quantity": "integer (required, min: 1, max: 999)"
    }
  ],
  "currency": "string (required, ISO 4217, e.g. 'USD')",
  "shipping_address_id": "string (optional, UUID)"
}

Response 201:
{
  "order_id": "string (UUID)",
  "status": "string (enum: created, processing, completed, cancelled)",
  "total_amount": "number (decimal, 2 places)",
  "created_at": "string (ISO 8601)"
}

Response 422:
{
  "error_code": "VALIDATION_ERROR",
  "message": "string",
  "details": [
    {
      "field": "string",
      "reason": "string"
    }
  ]
}

4. Obrada grešaka

Jedinstven format odgovora o grešci koji koriste svi endpoint-i:

Svaki odgovor o grešci mora sadržati najmanje: error_code (mašinski čitljiv), message (za čoveka) i opciono details (greške na nivou polja za 422 odgovore).

5. Ograničenja brzine i kvote

6. Verzionisanje

Kako API obrađuje breaking promene:

• URL verzionisanje: /api/v1/, /api/v2/
• Politika zastarevanja: v(N-1) podržan 12 meseci nakon izdavanja v(N)
• Sunset header: Sunset: Sat, 01 Mar 2027 00:00:00 GMT

7. Modeli podataka

Zajednički modeli podataka koji se koriste u više endpoint-a. Ovo izbegava ponavljanje iste šeme u svakoj specifikaciji endpoint-a.

Order:
  order_id: string (UUID, read-only)
  customer_id: string (UUID)
  status: string (enum: created, processing, completed, cancelled)
  items: array of OrderItem
  total_amount: number (decimal, 2 places)
  currency: string (ISO 4217)
  created_at: string (ISO 8601, read-only)
  updated_at: string (ISO 8601, read-only)

OrderItem:
  product_id: string (UUID)
  quantity: integer (min: 1)
  unit_price: number (decimal, 2 places, read-only)
  subtotal: number (decimal, 2 places, read-only)

Tipične greške u API FRD-u

1. Nema specifikacije grešaka. Definisati happy path (200 OK) a ne opisati odgovore o greškama (4xx, 5xx) — znači ostaviti potrošače API-ja da nagađaju kako da obrađuju neuspehe.

2. Nekonzistentni formati odgovora. Neki endpoint-i vraćaju { "error": "..." }, drugi { "message": "..." }. Jedinstven format grešaka za sve endpoint-e oslobađa potrošače API-ja pisanja posebnih handler-a za svaki endpoint.

3. Nedostatak ograničenja polja. „quantity: integer” je nepotpuno. „quantity: integer (required, min: 1, max: 999)” tačno govori programeru šta da validira.

4. Nema strategije verzionisanja. API bez plana verzionisanja kvari klijente kada se šema promeni. Definišite pristup verzionisanju pre nego što prvi endpoint bude isporučen.

Resursi

• FRD — kompletan vodič — pun FRD sa svih sedam sekcija
• FRD šabloni — standardni i API, spremni za korišćenje
• FRD generator prompt — napravite FRD koristeći AI
• PRD vs BRD vs FRD — trostruko poređenje