Specifikace REST API

V této kapitole si vysvětlíme pojem "specifikace". Velmi často se setkávám s tím, že vývojáři zaměňují pojmy "specifikace" a "dokumentace". Tedy ve zkratce:

Specifikace

• závazná dohoda o podobě systému

Dokumentace

• finální implementovaná podoba systému
• další materiály, manuály, atd.

Cílem je, aby se dohoda ve formě specifikace otiskla do zdrojového kódu v úplné shodě. Jinými slovy specifikace API může být přímo součástí dokumentace. Ta bývá sama o sobě mnohem rozsáhlejší a kromě seznamu endpointů může obsahovat například manuál použití, principy autentizace nebo důkladně popsaná workflow. Ukázkovou dokumentaci si můžete prohlédnout na stránce