reitit: overview and extensive guides - creating an API from scratch

Create a simple to follow set of guides to using Reitit and Reitit-ring (for web services), based on experiences of Reitit use over several commercial projects.

• Overview of reitit
• Creating web routes (REPL driven development)
• Building an API step by step with Reitit & Reitit-ring
  • Defining a router
  • Default routes
  • Muutanna middleware
  • Custom middleware
  • 404 error management (useful feedback)
  • Creating an api
  • Adding Specifications to the API
  • Authentication & Authorisation for the API
    • Developer token (JWT, roll-your-own)
    • RFC9421 HTTP Message Signatures (signing API requests)
  • Adding versioning to an API
  • Open API (Swagger UI) & API testing
    • adding an API key in the Swagger UI for testing
    • customising the Swagger UI / Company branding and standards
  • Designing Interceptors (how and why)

NOTE: examples of these aspects are already included in Practicalli Project Templates however this updated guide will help people understand the code in detail and the design choices made.

Related issues: #13#131

resources

• https://www.metosin.fi/blog/reitit
• https://www.metosin.fi/blog/reitit-ring
• https://github.com/metosin/reitit/blob/master/doc/ring/default_handler.md
• https://github.com/metosin/reitit/blob/90f3708e16a5099d7a7e0e8ea30fefc04daeb24d/modules/reitit-ring/src/reitit/ring.cljc#L371C7-L391
• https://bogoyavlensky.com/blog/auto-reloading-ring/
• https://blog.valerauko.net/2022/12/03/hot-reloading-and-reitit-in-the-frontend/
• https://github.com/lanjoni/re-frame-reagent-reitit-example
• https://clojureverse.org/t/passing-dependencies-into-ring-handlers-on-request-map-or-partial-ed-into-the-handler/8540/4

Start by reviewing the existing Practicalli Project Templates and the linked Reitit, Reitit-ring, and default-handler resources. Plan the guide around the listed topics, from routing through authentication, versioning, OpenAPI, and interceptors. Done means a simple, coherent set of step-by-step guides covering the requested API-building journey.