mxHeadless
REST API gateway for headless frontends on MODX 3. Resources, objects, OpenAPI, API keys, and OAuth
Web server
Default gateway prefix is /api (mxheadless_api_prefix). Requests to /api/v1/* must reach MODX index.php, where the OnHandleRequest plugin intercepts the API.
Apache
Enable mod_rewrite. MODX friendly URLs already route unknown paths to index.php. You usually do not need a separate rewrite block for /api.
Nginx
nginx
location / {
try_files $uri $uri/ /index.php?$args;
}The path /api/v1/* must not be served as static files and must not bypass PHP.
Fallback entry
Without rewrite, use assets/components/mxheadless/api.php.
- With PATH_INFO:
.../api.php/v1/health - Without PATH_INFO (typical nginx/Herd):
.../api.php?route=/v1/health
Bare api.php serves discovery. See Installation.
Proxy and HTTPS
Behind a load balancer, set mxheadless_trusted_proxies or rate limit and audit will see the proxy IP. The package does not rewrite URL scheme from X-Forwarded-Proto. Configure HTTPS on the web server or reverse proxy.