Endpoints accessed through /wp-json when using wp-env return Not Found

[johnhooks]

Why do all the REST API endpoints accessed through /wp-json/wp/v2 of the wp-env server return a HTML response of "Not Found".

In this closed issue, the solution provided is less than ideal:

#22648

Is there a specific limitation of wp-env that prevents the correct routing?

[johnhooks]

After some research I've found the answer below. This explains why the rest api routes aren't working, though is there a conventional way to enable permalinks through a script or configuration?

Enabling Pretty Permalinks creates / adds some lines to an .htaccess file, which activates a module that is part of your server's software. Now instead of returning 404 errors when your server discovers that the requested directories / files don't exist, it hands those requests over to WordPress, so they can be resolved by WordPress internally.

https://wordpress.stackexchange.com/questions/314808/why-does-wp-json-not-work-on-the-plain-permalink-structure

[johnhooks]

Found a solution to enable permalinks through cli, thank you @erikyo

wp-env run cli "wp rewrite structure '/%postname%'"

Which seemed like it was going to work.

But still getting "Not Found".

[johnhooks]

Resolved 🎉

In the comment above, we didn't formatted the structure argument properly. Use the following to enable permalink rest routing of wp-env through a cli command:

wp-env run cli "wp rewrite structure /%postname%/"

I believe this should be in the wp-env README.md, it was the first place I looked for a solution. I will follow up with a PR to add a note about rest api permalink routing.

[t-hamano]

As far as I know, the REST API endpoint relies on the permalink setting, which is the expected behavior of WordPress.
In the Settings > Permalinks menu, can't we just change "Permalink structure" to something other than "Plain" so we can access /wp-json/wp/v2?

However, on Windows and Linux, .htaccess may not be generated correctly when the permalink setting is updated, as reported in #45592. This is a problem not only with the REST API, but also with the combination of wp-env and the OS.

[erikyo]

Yes that's right: at first the WP deployment has "plain" permalinks as a structure but this is blocking us from using (for example) insomnia to test the rest-api and we are forced to login into WordPress and enable it.

Wouldn't it be better to provide this kind of setting directly in the wp-env configuration so we can test the api without further "complications"?

[t-hamano]

@erikyo

Wouldn't it be better to provide this kind of setting directly in the wp-env configuration so we can test the api without further "complications"?

That might make sense.

@johnhooks
How about we close this issue and focus on #49383? Because I think what we are addressing in this issue is expected behavior in WordPress core.

[johnhooks]

@t-hamano as a developer new to WordPress and being exposed to it by Gutenberg and block development, there is a large disconnect between the documentation of Gutenberg and WordPress.

I believe there needs to be a note about the default behavior of the rest-api and permalinks. I went to the REST API Handbook, and opened strait to "Using the REST API" and the note about permalinks is in "Key Concepts", so I initially missed it. While that could be blamed on me for not reading it cover to cover, I believe key stumbling blocks like this should be identified and specifically repeated throughout the documentation, because it is not apparent. Styling it as a warning, not as information, would also help call it out.

If you are using non-pretty permalinks, you should pass the REST API route as a query string parameter. The route http://oursite.com/wp-json/ in the example above would hence be http://oursite.com/?rest_route=/.

I will close this issue with a PR to expand the documentation. @mburridge do you have any thoughts on how best to accomplish this?

[t-hamano]

I think the default behavior of the rest-API and permalinks should be related to all WordPress environments, not just wp-env. Therefore, one idea might be to suggest moving the note about permalinks to a more obvious location in the GitHub repository of the REST API Handbook.

However, in the Block Editor Handbook, it is explained as if the endpoint is naturally /wp/v2/. For example, the "Building a list of pages" page. For these, it might be a good idea to add a note about endpoints.

[johnhooks]

The key issue here, is the default behavior of WordPress is to not enable permalinks by default. Though everything in the REST API Handbook, except for that little note, assume permalinks are enabled.

And I understand this isn't a Gutenberg issue, but I'm still unsure where or how to create an issue for the REST documentation.

[johnhooks]

However, in the Block Editor Handbook, it is explained as if the endpoint is naturally /wp/v2/. For example, the "Building a list of pages" page. For these, it might be a good idea to add a note about endpoints.

This is exactly the issue, all the documentation assumes permalinks.

[mburridge]

And I understand this isn't a Gutenberg issue, but I'm still unsure where or how to create an issue for the REST documentation.

You can create non-Gutenberg documentation issues over in the WordPress/Documentation-Issue-Tracker repo.

[johnhooks]

Thank you @mburridge, I will do that. Do you believe there is reason to include a note about this in the wp-env README.md and the Block Developer Handbook?

[mburridge]

I think that would be a fab idea. 👌

[johnhooks]

Thank you, I will get it done.

[eduwass]

That would be awesome, I just stumbled into this yesterday and was scratching my head for a bit until I found this issue, getting it documented somewhere will definitely help, thanks! 👍

[johnhooks]

@eduwass out of curiosity, where did you look for an answer first?

[eduwass]

@johnhooks → https://developer.wordpress.org/block-editor/reference-guides/packages/packages-env/

That was my first destination!

[johnhooks]

@eduwass that was not one of the locations on my radar. I'll add it to the list.

[noahtallen]

The key issue here, is the default behavior of WordPress is to not enable permalinks by default

Should we just make this the default for wp-env?

https://developer.wordpress.org/block-editor/reference-guides/packages/packages-env/

Also, I believe this file is updated automatically based on the packages/env/README.md file!

[johnhooks]

I support enabling permalinks by default in wp-env. Being a developer tool, having the rest api routed properly makes sense to me.

[noahtallen]

The permissions side of this should be fixed, but we should still change the default behavior.

[mburridge]

I believe that #50251 largely addresses this, so am closing this issue. If re-opening in order to keep alive the issue of adding an option to the wp-env settings, or having pretty permalinks enabled by default, then please remove the [Type] Developer Documentation label as this is no longer a documentation issue.

Preferably open a new issue to change the default wp-env environment.

[BrianHenryIE]

@johnhooks Your solution above, wp-env run cli "wp rewrite structure /%postname%/", did not work for me.

$ npx wp-env run cli "wp rewrite structure /%postname%/"
ℹ Starting 'wp rewrite structure /%postname%/' on the cli container. 

OCI runtime exec failed: exec failed: unable to start container process: exec: "wp rewrite structure /%postname%/": stat wp rewrite structure /%postname%/: no such file or directory: unknown
✖ Command failed with exit code 126
Command failed with exit code 126

Without quotes it appeared to work:

$ npx wp-env run cli wp rewrite structure /%postname%/ 
ℹ Starting 'wp rewrite structure /%postname%/' on the cli container. 

Success: Rewrite structure set.
Success: Rewrite rules flushed.
✔ Ran `wp rewrite structure /%postname%/` in 'cli'. (in 3s 443ms)

But wasn't really:

$ curl -I -s http://localhost:8888/wp-json/wp/v2/ | grep HTTP | grep -Eo "\d+" | tail -n 1
404

Adding --hard to the CLI command returned an error:

$ npx wp-env run cli wp rewrite structure /%year%/%monthnum%/%postname%/ --hard
ℹ Starting 'wp rewrite structure /%year%/%monthnum%/%postname%/ --hard' on the cli container. 

Success: Rewrite structure set.
Warning: Regenerating a .htaccess file requires special configuration. See usage docs.
Warning: Regenerating a .htaccess file requires special configuration. See usage docs.
Success: Rewrite rules flushed.
✔ Ran `wp rewrite structure /%year%/%monthnum%/%postname%/ --hard` in 'cli'. (in 4s 437ms)

Which I fixed by adding a wp-cli.wp-env.yml file containing:

apache_modules:
  - mod_rewrite

And mapping that in my .wp-env.json file:

{
  ...
  "mappings": {
        "wp-cli.yml": "./wp-cli.wp-env.yml"
  },
  ...
}

Although that's only worked for :8888 not :8889:

$ curl -I -s "http://localhost:8889/wp-json/wp/v2/" | grep HTTP | grep -Eo "\d+" | tail -n 1
404

Where the solution required using the tests-cli command:

$ npx wp-env run tests-cli wp rewrite structure /%year%/%monthnum%/%postname%/ --hard    
ℹ Starting 'wp rewrite structure /%year%/%monthnum%/%postname%/ --hard' on the tests-cli container. 

Success: Rewrite structure set.
Success: Rewrite rules flushed.
✔ Ran `wp rewrite structure /%year%/%monthnum%/%postname%/ --hard` in 'tests-cli'. (in 6s 184ms)

$ curl -I -s "http://localhost:8889/wp-json/wp/v2/" | grep HTTP | grep -Eo "\d+" | tail -n 1
200

Adding that to my .wp-env.json lifecycleScripts

{
  ...
  "lifecycleScripts": {
    "afterStart": "wp-env run tests-cli wp rewrite structure /%year%/%monthnum%/%postname%/ --hard"
  }
}

Seems to have worked well:

$ echo Y | npx wp-env destroy
ℹ WARNING! This will remove Docker containers, volumes, networks, and images associated with the WordPress instance.
? Are you sure you want to continue? Yes
✔ Removed WordPress environment. (in 28s 572ms)

$ npx wp-env start           
WordPress development site started at http://localhost:8888
WordPress test site started at http://localhost:8889
MySQL is listening on port 59065
MySQL for automated testing is listening on port 59130

 ✔ Done! (in 106s 660ms)

$ curl -I -s "http://localhost:8889/wp-json/wp/v2/" | grep HTTP | grep -Eo "\d+" | tail -n 1
200

Thanks for the help.

[zheng-maqro]

here is offcial doc for reference
https://github.com/WordPress/gutenberg/blob/trunk/packages/env/README.md#changing-the-permalink-structure