Guidelines

Pro snadnější orientaci v tomto průvodci jsem připravil několik vylepšení. V levém menu najdete základní přehled kapitol, které se věnují problematice designu REST API. Na konkrétních stránkách pak můžete najít další odkazy na podstránky, které daná témata upřesňují.

Odkazy

Pro navigaci v rámci průvodce se používají fialově podbarvené odkazy. Například odkaz na úvodní slovo. Odkazy vedoucí mimo tento web jsou zeleně a doplněné o značku. Například zde je odkaz na můj web. Občas lze narazit také na odkazy, které pomáhají s navigací na aktuální stránce. Například zde je odkaz na další nadpis.

Zvýraznění

Kromě běžného textu se snažím tučně zvýrazňovat důležité myšlenky. Obvykle se jedná o několik slov.

Je-li vhodnější zdůraznit delší text nebo myšlenku, pak najdete takový text zvýrazněný touto barevnou citací.

Formalizace

Některá slova mají ve větách důležitý význam. Jedná se o interpretace standardů nebo skutečně osvědčená praxe, na kterou se snažím upozornit. Slova jako musí - nesmí jsou proto podtržena světle červeně. Méně významné jsou výrazy může - nemůže - nemusí a proto jsou podtrženy světle modrou barvou. Podbarvené jsou také mé osobní preference uvozené slovem doporučuji.

Má doporučení nejsou nikdy méně restriktivní než standardy.

Související články

Vím, že některé konvence budí rozpaky a zaslouží si hlouběji vysvětlit. Proto průběžně dopisuji doplňující články k jednotlivým kapitolám a následně na ně v textu odkazuji. Ukážeme si to na rejstříku.

Barevné značení

Barevné čtverečky slouží ke zdůraznění nadpisů a rozlišení dobré a špatné praxe:

🟥 zásadně nedoporučeno

🟧 lze akceptovat s dobrým odůvodněním

🟩 doporučeno

Velmi podobně označuji příklady v kódu.

🔴 119.87.12.90                  -> zásadně nedoporučeno
🟠 http://www.api.com            -> lze akceptovat s dobrým odůvodněním
🟢 https://www.api.com           -> doporučeno

Není-li kód označen barevně, slouží jako běžná ukázka.

https://www.api.com              -> běžná ukázka