Gateway HTTP API
The generated HTTP references and OpenAPI documents for the routes a Gateway serves
TL;DR
MDK is agnostic about how you describe an API: it doesn't require a client or an app to adopt OpenAPI. The OpenAPI documents here are one way to describe the HTTP routes a Gateway serves, generated from the code that serves them.
Overview
The Gateway is MDK's HTTP entry point and this page covers its HTTP routes.
A Gateway serves two kinds of HTTP route: its own sign-in routes under /auth, and the routes of each app your stack declares.
Each is declared in code: the Gateway's in the route objects it registers, and an app's in its
route table (mdk-plugin.json).
The references listed on this page are generated from those declarations, showing what the code serves. Each comes as a Markdown page for people and an OpenAPI 3.1 document. Neither is a reference for MDK as a whole.
References
| Reference | What it covers | Generated from |
|---|---|---|
| Gateway HTTP API (OpenAPI 3.1) | The sign-in routes: request, response, and the status of every error code | The route objects the Gateway registers |
| Route-table fields | Every field an app's route table can declare | The route-table schema |
| Route-table schema | The JSON Schema mdk-plugin.json is checked against | Source; the app runtime's loader stays the authoritative check at startup |
Example apps
Each app documents its own routes.
An app doesn't have to generate a reference. These generate theirs from their route tables, as examples of an app set up this way:
| App | Where it lives | Reference |
|---|---|---|
MVP site's site app | The MVP site example in the MDK repository | HTTP reference (OpenAPI 3.1) |
| Reporting app | External repository | docs/http-api.md and docs/openapi.json in that repository |
The apps MDK ships list where each one documents its routes.
Next steps
- Declare an app's routes: the route table, controllers, and how errors reach a caller
- Configure the Gateway: its options, security model, and how it forwards requests to apps