Merge pull request #74 from jtc42/add-hypermedia-use-cases

Add additional resources to the docs

README.md

@@ -43,7 +43,7 @@ check the docs.
 <tr>
 <td>
 
-No Hypermdia
+No Hypermedia
 
 </td>
 <td>

docs/extending.md

@@ -16,7 +16,7 @@ to consider:
   `URLFor` has no Hypermodel type and leverages the base one, whereas HAL
   implements `HALHyperModel` and uses it to handle the cURIes logic. Siren uses
   the `SirenHyperModel` to move the different fields into `properties` and
-  `entitites`. This is usually required for Level 1+ Hypermdia formats
+  `entitites`. This is usually required for Level 1+ Hypermedia formats
 - Response Type: This is an optional class to define custom response behaviour.
   It could be lightweight like `SirenResponse` where only a jsonchema is
   checked, or it could be more complex like `HALReponse`. If no custom

docs/resources.md

@@ -0,0 +1,131 @@
+# Resources
+
+This page summarizes different resources around Hypermedia and some of its
+formats. The sections are public APIs currently using Hypermedia and text and
+video material about the topic for those interested.
+
+
+## Public APIs using Hypermedia
+
+The following services use Hypermedia for the public APIs. On top of these,
+there may be many more using it internal or for private (or paid) APIs which are
+not publicly documented.
+
+- [Github](https://docs.github.com/en/rest/meta/meta?apiVersion=2022-11-28#:~:text=hypermedia) - It uses basic level 0 hyperlinks.
+- [Amazon API Gateway](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateApiKey.html#:~:text=_links) - It uses HAL.
+- [Netflix's Genie](https://netflix.github.io/genie/docs/4.3.6/rest/#_hateoas) - It uses HAL.
+- [Paypal](https://web.archive.org/web/20240110000547/https://developer.paypal.com/api/rest/responses) - It uses a custom Hypermedia format.
+- [Spotify](https://developer.spotify.com/documentation/web-api) - It uses basic level 0 hyperlinks.
+- [Open Banking](https://openbanking.atlassian.net/wiki/spaces/DZ/pages/1077805207/Read+Write+Data+API+Specification+-+v3.1.2) - It uses JSON:API.
+- [Platform of Trust](https://design.oftrust.net/general-guidelines/use-hateoas) - It does not specify any concrete format.
+- [Elastic Path](https://elasticpath.dev/docs) - It uses custom Level 1 format.
+- [Family Search](https://www.familysearch.org/developers/docs/api/resources) - It uses its own format [GEDCOM X](http://gedcomx.org/).
+
+If you want to add another item to the list, submit a PR.
+
+
+## Useful resouces
+
+These are Python or Hypermedia-specific resources to get into the topic and
+delve deeper. Not all of the resources include Python code, that being said, the
+reader may benefit even if examples are in other languages.
+
+### Video
+
+Only english-speaking videos from "reviewed sources" are added, that is, videos
+published at conferences or by official organizations. This is to ensure a
+minimum quality for the content. There are more videos availables online as
+well.
+
+To keep the list clean from too outdated resources, only resources from 2012 or
+later are included.
+
+- [2023 - The Secrets to Smart, Flexible, Self Describing API - Michael Carducci - Great International Developer Summit](https://www.youtube.com/watch?v=zM5t6DaYrqM)
+- [2023 - Ditch heavy JS and KISS your frontend again with HTML over-the-wire - Alex Finnarn - Stir Trek](https://www.youtube.com/watch?v=lOmhnU51sQM)
+- [2023 - Back to the Future of Hypermedia in Python - Mario Munoz - North Bay Python](https://www.youtube.com/watch?v=MopeCQVSIUk)
+- [2023 - Back to the Future of Hypermedia in Django with - Mario Munoz - DjangoCon US](https://www.youtube.com/watch?v=LwH4ifjt3Y4)
+- [2022 - Return To Hypermedia: Solving Javascript Fatigue Using Fundamental Web Architecture - Carson Gross - ChariotSolutions](https://www.youtube.com/watch?v=LRrrxQXWdhI)
+- [2022 - How to JSON:API Quickly and Easily in Laravel - Matt Stauffer - Laracon](https://www.youtube.com/watch?v=C01dvypo4O4)
+- [2021 - Introduction to HATEOAS with Ketting - Evert Pot - APIdays NewYork](https://www.youtube.com/watch?v=cZ0e-HoPPJ8)
+- [2021 - RESTful API the HATEOAS Way - Ron Garlit - SWFL Coders](https://www.youtube.com/watch?v=jf1kVomeZ-U)
+- [2021 - Evolving Hypermedia - Tomasz Pluskiewicz - Nordic APIs](https://www.youtube.com/watch?v=PkBFSl_rESY)
+- [2021 - REST, HATEOAS & Django - It's OK to not use JSON... or Javascript - Carson Gross - DjangoCon US](https://www.youtube.com/watch?v=L_UWY-zHlOA)
+- [2021 - Elementary Full stack Development with Hypermedia and Java 21 - Patrik Duditš - Devoxx](https://www.youtube.com/watch?v=Ldi1hYQCfFY)
+- [2021 - Hypermedia without the hype - Tim Lytle - Comference](https://www.youtube.com/watch?v=b-so5HK8-9Y)
+- [2021 - JSON, JSON Schema, JSON-LD - Jakub Klímek - NPRG036 Data Formats](https://www.youtube.com/watch?v=U9wZpWlzdyI)
+- [2021 - Building Futureproof APIs with Spring HATEOAS - Greg Turnquist - JCon](https://www.youtube.com/watch?v=vsmrPW0eMyY)
+- [2021 - Why JSON-LD and what is it? - Samuel Rozé - API Platform Con](https://www.youtube.com/watch?v=zuPYqOsT-aw)
+- [2020 - Evolving architecture with DDD and hypermedia - Einar Høst - Domain-Driven Design Europe](https://www.youtube.com/watch?v=Q3hAPZVu3HI)
+- [2020 - Discoverable Hypermedia-Driven RESTful Web Services in Clojure - Daniel Zurawski - London Clojurians](https://www.youtube.com/watch?v=0V_F9Ko_Ic8)
+- [2020 - Building Flexible APIs with Spring HATEOAS - Greg Turnquist - Spring One](https://www.youtube.com/watch?v=0V_F9Ko_Ic8)
+- [2019 - Building RESTful Graph APIs that lasts - Sebastian Lambla - APIdays Barcelona](https://www.youtube.com/watch?v=FqCrltmDX0g)
+- [2019 - Testing APIs the Hypermedia way - Tomasz Pluskiewicz - APIdays Barcelona](https://www.youtube.com/watch?v=SNGGqW0hs20)
+- [2019 - Hail Hydra: The Future of Web APIs is Here - Devdutt Shenoi - FOSSMeet](https://www.youtube.com/watch?v=kDlQG6HTuYM)
+- [2019 - How to get along with HATEOAS without letting the bad guys steal your lunch? - Steve Poole, Graham Charters - Voxxed Days Luxembourg](https://www.youtube.com/watch?v=nMHJT2yn4pc)
+- [2019 - Bringing Hypermedia to the Masses - Tomasz Pluskiewicz - Nordic APIs Platform Summit](https://www.youtube.com/watch?v=F3Z6qye3LrE)
+- [2019 - How to get along with HATEOAS without letting the bad guys steal your lunch? - Steve Poole & Graham Charters - Devoxx](https://www.youtube.com/watch?v=IL2PlsbvUDs)
+- [2019 - Spring HATEOAS - Hypermedia APIs with Spring - Oliver Drotbohm, Greg Turnquist - SpringOne Platform](https://www.youtube.com/watch?v=o4cc6KzNrpI)
+- [2018 - Love to HATEOAS: Hypermedia for Fun and Profit - Gabriel Sullice - Decoupled Drupal Days](https://www.youtube.com/watch?v=-rPpGE_jvFw)
+- [2018 - Creating 3rd generation Web APIs using Hydra and Hydrus - Akshay Dahiya - PyCon India](https://www.youtube.com/watch?v=CMTQ-jdv2S8)
+- [2018 - Documenting Hypermedia APIs - Nick Bradley - API the Docs London](https://www.youtube.com/watch?v=_i1Qv-8WC8w)
+- [2018 - The JSON API Spec - Marco Otte-Witte - API Conference](https://www.youtube.com/watch?v=RSv-Yv3cgPg)
+- [2017 - Hypermedia APIs and HATEOAS - Volodymyr Tsukur - Wix Engineering Meetup](https://www.youtube.com/watch?v=ybwo_70jpGc)
+- [2017 - RESTful Hypermedia APIs - Kai Tödter - Jax London](https://www.youtube.com/watch?v=C6TXsI2hZMU)
+- [2018 - Real World REST and Hands-On Hypermedia - Dylan Beattie - DevTernity Conference](https://www.youtube.com/watch?v=RM7SXmu1QzE)
+- [2017 - Real World REST and Hands-On Hypermedia - Dylan Beattie - DotNext](https://www.youtube.com/watch?v=kPrTMj-BK14)
+- [2017 - Full Stack REST - Jimmy Bogard - DevReach Conference](https://www.youtube.com/watch?v=RqD0OjCcp9k)
+- [2016 - Get HATEOAS and Hypermedia right with Spring - Eugene Paraschiv - Sping I/O](https://www.youtube.com/watch?v=aThIuSsb_OA)
+- [2016 - Developing a developer-friendly hypermedia API with django-rest-framework and behave - Joost Cassee - PyCon Sette](https://www.youtube.com/watch?v=oGH0eIko_NE)
+- [2015 - Making Sense of Hypermedia APIs - Hype or Reality - Laura Heritage - Akana Webinar](https://www.youtube.com/watch?v=0fPuerB3AL0)
+- [2015 - Using Hypermedia APIs to Drive Interactive Mobile Applications - Benjamin Greenberg - Full Stack Toronto Conf](https://www.youtube.com/watch?v=EaVqkfsPmvQ)
+- [2016 - The Rest of ReST - Dylan Beattie - NDC Conference](https://www.youtube.com/watch?v=g8E1B7rTZBI)
+- [2015 - Hypermedia APIs - The Rest of REST - Chris Marinos - SEM JS](https://www.youtube.com/watch?v=y7nG05MTRus)
+- [2015 - SmartData Webinar JSON LD - Brian Sletten - DataVeristy](https://www.youtube.com/watch?v=NYIBeDDGfEk)
+- [2015 - Hypermedia The Good, the Bad and the Ugly - Mike Stowe - Devnexus](https://www.youtube.com/watch?v=8HC7BsWU0hE)
+- [2014 - Cutting-edge APIs using hypermedia at BSkyB - Adriana Vasiu - EuroPython](https://www.youtube.com/watch?v=7rSLyLMaWXQ)
+- [2014 - Hypermedia - The rest of REST - Steven Cummings - Cerner DevCon](https://www.youtube.com/watch?v=39_qe6jE2PM)
+- [2014 - On the Edge of Hypermedia - Keith Casey - Midwest.io](https://www.youtube.com/watch?v=39_qe6jE2PM)
+- [2014 - Hypermedia: Taking your API to the next level - Unknown - NERD Summit](https://www.youtube.com/watch?v=c7Zyv1AL3dQ)
+- [2012 - Designing Hypermedia APIs - Steve Klabnik - Rails Conf](https://www.youtube.com/watch?v=g4sqydY3hHU)
+- [2012 - Designing Hypermedia APIs - Steve Klabnik - TwilioCon](https://www.youtube.com/watch?v=LvtUsJKfeXg)
+
+If you want to add another item to the list, submit a PR.
+
+### Blogs and Articles
+
+Here there are blog posts and articles from different sources, some
+organizations and some individuals. The length varies but each has its own
+value.
+
+- [2024-01-30 - Pradeep Loganathan - HATEOAS](https://pradeepl.com/blog/rest/hateoas/)
+- [2023-11-09 - Antonio W. Lagnada - ReST HATEOAS Best Practices](https://www.kapresoft.com/software/2023/11/09/rest-hateoas-best-practices.html)
+- [2023-11-04 - Lokesh Gupta - HATEOAS Driven REST APIs](https://restfulapi.net/hateoas/)
+- [2023-03-26 - Mahul Mohan - REST API Design: Advanced HATEOAS Implementation and Use Cases](https://codedamn.com/news/backend/rest-api-design-advanced-hateoas-implementation)
+- [2022-10-02 - GeeksforGeeks - HATEOAS and Why It’s Needed in RESTful API?](https://www.geeksforgeeks.org/hateoas-and-why-its-needed-in-restful-api/)
+- [2021-04-20 - Luca Christen - Using HATEOAS with REST APIs](https://engineering.3ap.ch/post/using-hateoas-with-rest/)
+- [2019-06-01 - Tomasz Pluskiewicz - Testing APIs Hypermedia-style](https://t-code.pl/blog/2019/06/testing-hypermedia-api/)
+- [2018-05-30 - Jason Desrosiers - The Hypermedia Maturity Model](https://8thlight.com/insights/the-hypermedia-maturity-model)
+- [2018-04-11 - Jason Desrosiers - Decoupling the Client and Server with Hypermedia](https://8thlight.com/insights/decoupling-the-client-and-server-with-hypermedia)
+- [2018-03-21 - Jason Desrosiers - Turning Up The Good On REST APIs](https://8thlight.com/insights/turning-up-the-good-on-rest-apis)
+- [2017-01-31 - Bill Doerrfeld - Designing a True REST State Machine](https://nordicapis.com/designing-a-true-rest-state-machine/)
+- [2016-01-19 - Kristopher Sandoval - How to Improve API Experience Using Hypermedia](https://nordicapis.com/improve-api-experience-using-hypermedia/)
+- [2014-03-11 - Kevin Sookocheff - On choosing a hypermedia type for your API - HAL, JSON-LD, Collection+JSON, SIREN, Oh My!](https://sookocheff.com/post/api/on-choosing-a-hypermedia-format/)
+- [2008-10-20 - Roy T. Fielding - REST APIs must be hypertext-driven](https://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven)
+
+If you want to add another item to the list, submit a PR.
+
+### Books
+
+There are not too many books which a strong focus on hypermedia or HATEOAS,
+however the following are complementary and in-line with designing discoverable
+and evolvable REST APIs.
+
+- [2021 - Building Microservices - Sam Newman - O'Reilly](https://www.oreilly.com/library/view/building-microservices-2nd/9781492034018/)
+- [2017 - RESTful Web Clients - Mike Amundsen - O'Reilly](https://www.oreilly.com/library/view/restful-web-clients/9781491921890/)
+- [2016 - RESTful API Design: Best Practices in API Design with REST - Matthias Biehl - API-University Press](https://www.amazon.com/RESTful-API-Design-Practices-API-University-ebook/dp/B01L6STMVW)
+- [2013 - RESTful Web APIs - Leonard Richardson, Mike Amundsen, Sam Ruby - O'Reilly](https://www.oreilly.com/library/view/restful-web-apis/9781449359713/)
+- [2012 - Designing Hypermedia APIs - Steve Klabnik - Self Published](http://www.designinghypermediaapis.com/index.html)
+- [2011 - Building Hypermedia APIs With HTML5 and Node - Mike Amundsen - O'Reilly](https://www.oreilly.com/library/view/building-hypermedia-apis/9781449309497/)
+- [2010 - REST in Practice: Hypermedia and Systems Architecture - Jim Webber, Savas Parastatidis, Ian Robinson - O'Reilly](https://www.oreilly.com/library/view/rest-in-practice/9781449383312/)
+
+If you want to add another item to the list, submit a PR.

mkdocs.yml

@@ -28,3 +28,4 @@ nav:
   - Basic Usage: 'basics.md'
   - Advanced Usage: 'advanced.md'
   - Extending FastAPI-HyperModel: 'extending.md'
+  - Additional Resources: 'resources.md'