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í červeně podbarvené odkazy. Například odkaz na úvodní slovo. Odkazy vedoucí mimo tento web jsou černě 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 osvědčenou praxi, 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é znač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

Složené závorky slouží jako placeholder. Typicky se jedná o identifikátory:

https://www.api.com/{id}         -> placeholder {id}