Jak psát API
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
-
http://smizell.com/weblog/2014/solving-fizzbuzz-with-hypermedia
-
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
-
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)
-
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
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
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