Jak psát API

Znáte Jak psát web, návod na HTML stránky? Toto je Jak psát API, návod na webová API.

Co jsou webová API?

API znamená application programming interface a v IT tato zkratka znamená spoustu věcí. Všechny ty věci by se daly zhruba shrnout do českého slova rozhraní. Je to tedy nějaký způsob, jakým se domlouvají systémy, aplikace, knihovny nebo i jednotlivé objekty mezi sebou.

Webová API jsou souhrnný název pro taková rozhraní, která jsou založená na stejných technologiích, na jakých běží web. Tzn. že jako nosný protokol zpravidla používají HTTP nebo HTTPS a komunikace se většinou odehrává ve formátech jako XML, JSON, apod. Příkladem budiž třeba API Facebooku.

Schválně nepoužívám výraz REST API, protože znamená něco trochu jiného. Nejblíže popisu výše je možná HTTP API, ale označení webová API mi přijde o dost lidštější a v angličtině se navíc spojení web APIs zcela běžně používá.

Co má společného Jak psát API s Jak psát web?

Dalo by se říci že nic, protože Jak psát API píše úplně jiný člověk a žádné partnerství s Jak psát web neexistuje. Název jsem ale nezvolil proto, abych se přiživil na slávě JPW a Yuhůa. Vybral jsem jej proto, že ve webových API vidím velkou budoucnost a věřím, že JPA by mohlo jednou být stejně potřebné, jako dříve JPW.

Doby, kdy si firmy hledaly cestu na Internet (tehdy jednoznačně s velkým I!) a kdy najednou i pekař ve vaší ulici zjisti, že by nejspíš měl mít nějaký web, ty jsou za námi. Čeká nás ale dost podobné období na poli webových API - díky potřebě integrací, mobilních aplikací, Internet of Things aj. trendům brzy i kdejaká menší firma zjistí, že bez API jako kdyby neexistovala.

Navíc věřím tomu, že nejlepší způsob jak psát API je tvořit je stejným způsobem, jakým tvoříme web. Tzn. uplatnit co nejvíce možnosti HTTP, hyperlinků, použitelnosti, atd.

Obsah

• Základy
• Životní cyklus návrhu
• Dokumentace
• Verzování
• Chyby
• Autentizace a autorizace
• Parametrizace odpovědi
• HTTP
  • Content Negotiation
  • Kešování
  • HTTP 2.0
• REST
  • REST vs. SOAP
  • Sloveso v URL je "code smell"
  • Asynchronní odpovědi, hooky
  • Hromadné požadavky (bulk, batch)
• Hypermedia (HATEOAS)
  • Formáty
• JSON
  • Schema
  • PATCH
• Nástroje a knihovny
  • Python
  • Ruby
  • C# a .NET
• Další zdroje

Jak přispívat?

Písmenka

Pište v Markdownu a posílejte pull requesty. Uvítám v issues opravy chyb, nové články i nejrůznější polemiky. Commit messages pište česky a jako celé věty (s tečkou na konci).

Kvalita a objektivita

Nemám patent na rozum a zároveň mám určité názory, jak by se měly věci dělat. Obsah Jak psát API tím rozhodně je a bude ovlivněn. Pokud najdete chybu, pokud byste nad nějakým tématem rádi polemizovali nebo si myslíte, že si zaslouží smířlivější a obecnější tón, pojďte s tím do issues. Věřím v pluralitu názorů a vzájemné obohacení z věcných diskusí.

Tiráž

Kontakt

Založte issue zde, nebo pište na [email protected].

Autor

Jak psát API založil a spravuje Honza Javorek. Honza pracuje pro Apiary, ale tento projekt je jeho soukromou aktivitou. (V zásadě by se dalo říct, že si zde ukládám zajímavé informace a třídím si své myšlenky.)

Chcete-li, aby vám Honza odvyprávěl zde sepsané vědomosti naživo, domluvte se s ním e-mailem na školení nebo přednášce.

Licence? CC BY-SA

(cc) 2014 Jan Javorek <[email protected]>

Toto dílo podléhá licenci Creative Commons Uveďte autora-Zachovejte licenci 3.0 Česko.