librematch:design:backend:openapi:start

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision		 Previous revision
librematch:design:backend:openapi:start [2022-10-27 22:52] – removed - external edit (Unknown date) 127.0.0.1librematch:design:backend:openapi:start [2022-11-28 21:51] (current) – [Deviations from Guidelines] simonsan
Line 1: Line 1:
 +====== OpenAPI ======
 +
 +===== Documentation Generation =====
 +
 +FastAPI will take care of generating the documentation page. [[https://fastapi.tiangolo.com/features/#automatic-docs|We can choose from different UIs]]:
 +
 +  - ** [[https://github.com/Rebilly/ReDoc|ReDoc]] ** \\ with a [[ https://github.com/Redocly/redocly-cli|CLI]] that lints our OpenAPI spec
 +  - ** [[https://github.com/swagger-api/swagger-ui|SwaggerUI]] **
 +
 +**ReDoc** has premium services and we need to check if although it looks more beautiful it's worth to opt in to their free stage or if **SwaggerUI** is enough.
 +
 +===== API first principle =====
 +
 +We follow the API first principle. Meaning that we define our API first, before generating the backend stub and coding its implementation.
 +
 +Our OpenAPI spec acts like a **single source of truth (SSOT)**. Test cases are generated from the OpenAPI spec and the backend implementation needs to adhere to them.
 +
 +Our design follows a few different design guidelines:
 +
 +  - [[ https://opensource.zalando.com/restful-api-guidelines/ | Zalando RESTful API Guidelines ]]
 +  - [[ https://docs.microsoft.com/en-us/azure/architecture/best-practices/api-design | Microsoft API Design Best Practices ]]
 +  - [[ https://mathieu.fenniak.net/the-api-checklist/ | Web API Checklist by Mathieu Fenniak ]]
 +
 +===== Deviations from Guidelines =====
 +  - We don't use **kebab case** and **snake case** instead as the dash can easily introduce bugs as it can be interpreted as a minus sign.
 +  - We might want to use [[https://calver.org/|CalVer]] ([[https://docs.github.com/en/rest/overview/api-versions?apiVersion=2022-11-28|Read github notes]])
 +
 +===== Assigning Scopes =====
 +<WRAP center round todo 60%>
 +https://opensource.zalando.com/restful-api-guidelines/#105
 +</WRAP>
 +