Jak psát API

toc.md

Jak psát API

• https://github.com/apiaryio/api-blueprint/tree/resource-blueprint

Uvidím, jak se to vydaří. Dokážu k těm tématům udělat ukázky, můžu si přichystat příklady, atd. Ukázat nějakou věc na příkladu si taky vezme čas. Mimochodem - mít na Jak psát API složku s funkčními příklady, to je super nápad!

Úvod do seriálu a problematiky

• proč se zabývat HTTP APIs, boom v poslední době
• způsoby tvorby API nad HTTP
• hypermedia APIs jako jeden ze způsobů tvorby API, vztah k Fieldingovi
• analogie hypermedia API a browsování webu RWA1, http://stackoverflow.com/questions/20775954/restful-websites-vs-restful-apis-whats-the-difference-and-does-it-matter/20793975#20793975 - puzzle hra, non-restful website
• výhody a nevýhody hypermedia APIs (scaling, evolvability - change tolerant, abstracting URIs)
• whatever you use, make your API opinionated and consistent
• shared knowledge, shared server/client tooling

Kin Lane říká, že ... A decade ago, businesses were still working to understand the importance of having a website for doing business. Today, businesses are beginning to understand the similar importance in having an API.

Obchodní posun https://www.youtube.com/watch?v=rdBd_FP17kg

Hypermedia designs scale better, are more easily changed and promote decoupling and encapsulation, with all the benefits those things bring. http://steveklabnik.github.io/hypermedia-presentation/#12

Design

• http://amundsen.com/blog/archives/1037
• WIP pattern https://mail.google.com/mail/u/0/#label/Diskuse/1488353ec9939d9e

RESTful - opakování

• https://stackoverflow.com/questions/19843480/s3-rest-api-and-post-method/19844272#19844272
• http://www.itnetwork.cz/stoparuv-pruvodce-rest-api
• http://roy.gbiv.com/untangled/2009/it-is-okay-to-use-post
• http://thereisnorightway.blogspot.cz/2011/01/uri-design-in-rest.html
• HTTP: https://github.com/for-GET/know-your-http-well
• http://restcookbook.com/
• co je REST, Fielding
• 5 REST constraints
• proč by mělo být HTTP API RESTful, co to přináší, evolvability, scalability, atd. https://twitter.com/fielding/status/376835835670167552
• Leonard Richardson's Maturity Model (4 steps) http://martinfowler.com/articles/richardsonMaturityModel.html, http://www.crummy.com/writing/speaking/2008-QCon/act3.html
• jak k RESTful API dojít, co implementovat
• vlastnosti HTTP verbs (indepotency, repeatability), RWA1.8, RWA3.33
• resources vs. representations, RWA3, užití media types
• http://blog.steveklabnik.com/posts/2011-07-03-nobody-understands-rest-or-http & http://blog.steveklabnik.com/posts/2011-08-07-some-people-understand-rest-and-http
• http://mark-kirby.co.uk/2013/creating-a-true-rest-api/
• https://restful-api-design.readthedocs.org/en/latest/
• http://codeplanet.io/principles-good-restful-api-design/
• http://blogs.clevertech.biz/startupblog/successful-rest-api-design

HATEOAS

• https://speakerdeck.com/zdne/robust-mobile-clients-v2

• https://twitter.com/zdne/status/471458410001465344

• http://smizell.com/weblog/2014/solving-fizzbuzz-with-hypermedia

• https://www.youtube.com/watch?v=0PB_pO_jU38

• http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven

• http://gale.re/readability/2796094 = http://www.infoq.com/news/2013/08/mamund-on-api-design

• http://www.slideshare.net/rnewton/2013-06q-connycrestfulwebapis

• http://blog.steveklabnik.com/posts/2012-02-23-rest-is-over

• HATEOAS RWA4

• FSM, transitions = URLs

• URI vs URL

• analogie s webem

• application state / resource state (RWA1.10, RWA1.11)

• billboard URL (abstracting URIs, evolvability)

• self discoverability

• rels

• HTML formuláře a odkazy vs. API, URI templates, link headers

• jak by měl vypadat klient nové generace, příklady (rels, discoverability, evovlvability) RWA5, RWA1.15

• jak by měl vypadat server nové generace, příklady (media types, content negotiation, no versions)

• http://timelessrepo.com/haters-gonna-hateoas

• https://blog.heroku.com/archives/2014/1/8/json_schema_for_heroku_platform_api

• https://37signals.com/svn/posts/3373-getting-hyper-about-hypermedia-apis vs http://blog.balancedpayments.com/restful-hypermedia-apis/

• shared knowledge, shared server/client tooling

• https://mail.google.com/mail/u/0/#search/in%3Aanywhere+label%3Adiskuse+is%3Aunread/144b15b7fd647985

• http://www.programmableweb.com/news/hypermedia-apis-benefits-hateoas/how-to/2014/02/27

• http://www.slideshare.net/rnewton/reusable-libraries-for-hypermedia-clients

• https://speakerdeck.com/ammeep/exist-in-the-web-not-on-it

• http://channel9.msdn.com/Shows/Azure-Friday/HATEOAS-REST-and-Hypermedia-Primer-with-Mat-Velloso?utm_source=dlvr.it&utm_medium=twitter

http://amundsen.com/blog/archives/1067#IDComment87517941 - hypermedia clients are harder to write, ... it took SOAP about ten years before folks started to see the limiting factors. it might be the same for JSON-esque models, too.

• http://hypermedia.apievangelist.com/
• http://apievangelist.com/2014/04/15/what-are-some-good-examples-of-hypermedia-apis/

Hypermedia formats

• proč je na prd používat čistý JSON, XML
• vyhody hypermedia types http://amundsen.com/blog/archives/1069
• http://amundsen.com/blog/archives/1059 - proc se zabyvat nejakym smetim kolem URL, fake hypermedia RWA4.55
• jaké hypermedia formáty už existují pro JSON/XML
• jaké jsou ve fázi draftů, k čemu se hodí, atd.
• zoo, RWA10.199
• vlastní media type, registrace, proč to dělat, nejdřív najít existující, pak rozšiřovat obecné, proč nevymýšlet svůj, atd.

Kazdy me pri hypermedia standards posle k http://xkcd.com/927/, ale ono je to spis jak obrazky - kazdy na trochu jiny use case.

ruzne hypermedia formaty (widely used) http://amundsen.com/hypermedia/

Caching

• RWA11
• stateless, cache
• co znemaná stateless, uchovávání údajů o uživatelích na serveru (rate limiting je porušení, ale neva)
• jak řešit stavovost (posílat s každým požadavkem, atd.)
• čím víc stateless, tím lépe cachovatelné
• techniky cachování, škálování na miliony uživatelů
• if modified, atd. tyhle hlavičky
• etags
• HTTP 304 not modified

Parametrizace odpovědi

• pagination
• zooming
• fields https://blog.apigee.com/detail/restful_api_design_can_your_api_give_developers_just_the_information
• prefer header https://mail.google.com/mail/u/0/#search/label%3Adiskuse+is%3Aunread/146c9e3540f9a58e

Authorization

• https://mail.google.com/mail/u/0/#search/label%3Adiskuse+is%3Aunread/145b5dc83b5077ea
• RWA11
• stateless
• HTTP Basic
• OAuth
• http://aaronparecki.com/articles/2012/07/29/1/oauth2-simplified

stateless & sessions: http://stackoverflow.com/questions/3105296/if-rest-applications-are-supposed-to-be-stateless-how-do-you-manage-sessions krasne vysvetleni lidskymi slovy

• https://mail.google.com/mail/u/0/#label/Diskuse/146590f88837cab2

HTTP2.0

• RWA11
• řešení problémů, se kterými vám nepomůže ani hypermedia, jsou to problémy HTTP obecně
• SPDY
• http://www.slideshare.net/mnot/what-http20-will-do-for-you
• http://www.pcworld.com/article/2061189/next-gen-http-2-0-protocol-will-require-https-encryption-most-of-the-time-.html

Error handling

• HTTP errors explained
• best practices http://soabits.blogspot.cz/2013/05/error-handling-considerations-and-best.html
• https://github.com/blongden/vnd.error

Content Negotiation, versioning

• media types, languages, encoding, charset, ...
• versioning
• http://thereisnorightway.blogspot.cz/2011/02/versioning-and-types-in-resthttp-api.html

Dokumentace API

• great API = great documentation
• JSON schema
• OPTIONS
• rels a odkazy do dokumentace
• text/html format
• doc driven API development: Apiary https://www.youtube.com/watch?v=BJtkES160qs, http://apiblueprint.org/
• http://developers.helloreverb.com/swagger/
• WSDL, https://en.wikipedia.org/wiki/Web_Services_Description_Language
• WADL https://stackoverflow.com/questions/1312087/what-is-the-reason-for-using-wadl
• http://amundsen.com/blog/archives/1067
• RAML vs. Blueprint vs. Swagger: https://mail.google.com/mail/u/0/?q=label%3Adiskuse+is%3Aunread+#search/label%3Adiskuse+is%3Aunread/14701d19de388ceb

PATCH protokol

• RWA11
• PATCH - proč použít formát na PATCH (složitější změny atomicky)
• https://github.com/apicraft/detroit2013/wiki/PATCH-and-partial-updates
• https://mail.google.com/mail/u/0/#search/label%3Adiskuse+is%3Aunread/148130c65c08d5b1
• https://mail.google.com/mail/u/0/#label/Diskuse/14879ea8227ec860

Tooling pro Python

• Django REST framework, Tastypie
• Flask RESTful, Eve
• knihovny na HAL, JSON schema, content negotiation, PATCH protokol

---

RWA - RESTful Web APIs, Leonard Richardson & Mike Amundsen (O'Reilly 2013)

---

Způsob jakým téma předkládat - já to dělám takto a líbí se mi to proto a proto, vidím v tom tyto a tyto výhody. Nikomu tento způsob nenutím, máme na výběr spoustu možností a formátů, nevím nic o vaší konkrétní aplikaci (třeba se tam nejlépe hodí SOAP, protože pracuje s nějakým legacy systémem, kde je SOAPu plno), ale sám používám tento nejraději atd. - http://amundsen.com/blog/archives/1120 (způsob jak se pokusit vyhnout dementním komentářům)

• http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api
• http://rest.elkstein.org/
• https://speakerdeck.com/milancermak/http-api-and-python
• http://blog.luisrei.com/articles/rest.html
• praktická část, kde ukážu jak vytvořit jednoduché hypermedia API v Djangu, Flasku?
• RWA11 pokrývá několik článků dohromady, v podstatě jde o co nejlepší a největší využití schopností HTTP pro API, HTTP: https://github.com/apicraft/detroit2013/wiki/What-can-we-use-from-HTTP%3F
• ze všeho musí jasně plynout proč to dělat - co je výhodou a kdy se to vyplatí
• http://blog.balancedpayments.com/restful-hypermedia-apis/
• tvorba resourců atd.: navrhování API je UI/UX práce, navrhujeme frontend něčeho, co budou používat lidé https://www.youtube.com/watch?v=BJtkES160qs, nemá to kopírovat ORM pod kapotou, ale mělo by to být založeno na use-casech
• https://github.com/apicraft/detroit2013/wiki
• jak vysvětlit affordances: https://www.youtube.com/watch?v=NK1Zb_5VxuM
• https://github.com/seancribbs/webmachine-ruby
• https://apispark.com/
• CORS: http://enable-cors.org/
• sloveso v URL: https://mail.google.com/mail/u/0/#search/label%3Adiskuse+is%3Aunread/1478a0b13774f409
• float v API, měny: https://mail.google.com/mail/u/0/#search/label%3Adiskuse+is%3Aunread/1478a0b13774f409

API Chaining

https://mail.google.com/mail/u/0/#label/Diskuse/148efbc2dd448440 http://www.slideshare.net/bobdobbes/api-abstraction-api-chaining