Application lifecycle

This page provides a high-level overview of the full application lifecycle, from bootstrapping to response output. Each step links to a detailed page — this page does not repeat their content.

Bootstrap

The bootstrap phase runs once when the module file is loaded. It sets up the API structure before any HTTP request is handled.

1. Create an API instance — new Api() creates the top-level container. Read more about the API instance.
2. Configure — configure() sets options like trailingSlashes and jsonFlags. Read more about configuration.
3. Set base path — setBasePath() defines the root path prefix for all endpoints. Read more about the base path.
4. Add services — addService() registers services. Each service's init() method is called, which registers endpoints, hooks, and child services. Read more about services.
5. Add hooks and plugins — Request hooks and plugins can be added at the API, service, or endpoint level. Read more about request hooks. Read more about plugins.
6. Run — run() validates the configuration (no duplicate service names or endpoint paths), registers a ProcessWire URL hook listener for each endpoint path, and locks the instance to prevent further mutations. Read more about running the API.

Request handling

The request handling phase runs for each incoming HTTP request that matches a registered endpoint path.

1. Request object — A Request object is created containing the HTTP method, path, query parameters, headers, body, and files. Read more about requests.
2. On-request hooks — On-request hooks are executed in order: API → services → endpoint. Headers set by them are added to every response, including the OPTIONS and error responses. Read more about on-request hooks.
3. OPTIONS shortcut — If the request method is OPTIONS, a 200 response with an Allow header is returned immediately. No other hooks or handlers are executed. Read more about endpoints.
4. Body validation — If the request body is malformed JSON, a 400 response is returned. Read more about requests.
5. Handler lookup — The library looks up a handler for the request method. If no handler is registered, a 405 response with an Allow header is returned. Read more about endpoints.
6. Authentication — If an authenticator is configured, it runs now. The closest level to the endpoint wins (endpoint > service > API). A level that opts out with skipAuthentication() ignores the authenticators of the levels above it. Read more about authentication.
7. Authorization — All authorization callbacks in the chain run in order: API → services → endpoint. A level that opts out with skipAuthorization() ignores the callbacks of the levels above it. Read more about authorization.
8. Before hooks — Before hooks are executed in order: API → service → endpoint. Read more about hook execution order.
9. Handler execution — The endpoint handler runs and returns a Response. Read more about responses.
10. After hooks — After hooks are executed in order: endpoint → service → API. Read more about hook execution order.
11. Error handling — If an ApiException is thrown at any point, error hooks are executed and the exception is converted to a JSON response. Other exceptions are passed to the exception handler, if defined. Read more about error handling. Read more about error hooks.
12. JSON response — The final response is encoded as JSON and sent to the client.