The notion of a “site” is different for headless projects. In traditional Wagtail, the domain or port of a Wagtail site are where Wagtail will serve content and the location the end user visits to find the site.
But in Headless Wagtail, the domain or port that the end user uses and domain or port that Wagtail serves content on will be different. For example, the end user may visit www.wagtail.org, and the website could be a Next.js app that queries a Wagtail instance running at api.wagtail.org.
Wagtail’s current API implementation will check the host header and port to find the site so that it only returns pages under that site. This means that your site record must be set to api.wagtail.org. However, when Wagtail generates URLs, these URLs need to be generated for www.wagtail.org.
The Wagtail API only allows requests from one site at a time to make sure any site listings are isolated from other sites by default. But the API could be improved in the following ways:
- Allow the site to be specified in the API request.
- Allow all pages across all sites to be queried on an opt-in basis.
With these approaches, the site record in the Wagtail admin of Headless Wagtail would be set to the domain or port that the end user sees so URLs could be reversed correctly. All API requests would specify the site as a GET parameter.