Gatsby: [gatsby-source-wordpress] Support non-pretty permalinks

[robinmetral]

Summary

I'd like to reopen the discussion that was started in this PR last june about supporting non-pretty urls in gatsby-source-wordpress.

As mentioned in WordPress's REST API Handbook, the typical WP API endpoint is http://oursite.com/wp-json/, unless we have non-pretty permalinks:

If you’re 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=/.

This is also the case if the WordPress instance is hosted on a subdomain, for example admin.oursite.com.

The endpoint here is http://oursite.com/?rest_route=/, and hitting http://oursite.com/wp-json/ returns a 404.

Motivation

I think it makes sense to host the WordPress endpoint on a subdomain, so that editors can easily reach the CMS. For this gatsby-source-wordpress needs to support endpoints with query params like http://oursite.com/?rest_route=/

[robinmetral]

(also I think that this part of the plugin's docs can be updated: changing permalinks to anything other than Plain won't work if WordPress is hosted on a subdomain)

[robinmetral]

There seems to have been a problem on my end, a brand new installation of WordPress on a subdomain exposes as expected the /wp-json endpoint.

[re1]

I am running into a similar issue with a local docker instance based on https://docs.docker.com/compose/wordpress/. localhost:8080/wp-json/ cannot be found while localhost:8080/?rest_route=/ works fine.

Changing the permalink settings did not help either.

[robinmetral]

@re1 feel free to reopen this issue if you'd like, even though it was solved for me I still think that supporting non-pretty permalinks would be a good thing :slightly_smiling_face:

[re1]

Thank you for the fast response :+1: It seems like I do not have permission to re-open your issue.

even though it was solved for me I still think that supporting non-pretty permalinks would be a good thing

This is especially true as ?rest_route= seems to be the more robust solution anyway. The WordPress Developer Handbook even states that

Clients should keep this variation in mind and ensure that both routes can be handled seamlessly.

[robinmetral]

Reopening :+1:

[wardpeet]

Hi @re1!

Sorry to hear you're running into an issue. To help us best begin debugging the underlying cause, it is incredibly helpful if you're able to create a minimal reproduction. This is a simplified example of the issue that makes it clear and obvious what the issue is and how we can begin to debug it.

If you're up for it, we'd very much appreciate if you could provide a minimal reproduction and we'll be able to take another look.

Thanks for using Gatsby! 💜

[re1]

Hey @wardpeet!
Please excuse my late response. I am building upon gatsby-starter-default including gatsby-source-wordpress through the following lines inside gatsby-config.js.

{
  resolve: 'gatsby-source-wordpress',
  options: {
    baseUrl: process.env.WP_URL,
    protocol: process.env.WP_PROTOCOL,
    hostingWPCOM: false,
    useACF: false,
    includedRoutes: ['**/media', '**/pages', '**/posts'],
  },
},

WordPress was hosted locally using Docker as described here: https://docs.docker.com/compose/wordpress/.

As WordPress does not expose wp-json (http://localhost:8080/wp-json/) by default I was unable to use the Gatsby WordPress source. This can usually be resolved by setting pretty permalinks.

Changing the permalink settings did not help either.

Because of an issue in my docker setup pretty permalinks did not work for me, which is why this became a problem for me.

WordPress itself recommends using ?rest_route= (http://localhost:8080/?rest_route=/) instead as it will also work without permalink configuration ([1]).

To reproduce this issue setting up the gatsby-wordpress-starter with a local WordPress instance should be enough as non-pretty permalinks are used by default.

[cjhaviland]

Hey @wardpeet and @re1 ,

I am just setting up GatsbyJS to make a new website for my podcast that uses wordpress and I ran into the same issue. Our Wordpress installation is using the non-pretty permalinks, and we can't change that without breaking our RSS feed.

Anyway... since I knew what was going on here, and I'd like to continue learning and trying GatsbyJS I took a stab at fixing this. I changed the code to allow you to configure using the Non-Pretty Permalinks instead, but I honestly don't now how to build and test node_modules...

[gatsbot[bot]]

Hiya!

This issue has gone quiet. Spooky quiet. 👻

We get a lot of issues, so we currently close issues after 30 days of inactivity. It’s been at least 20 days since the last update here.

If we missed this issue or if you want to keep it open, please reply here. You can also add the label "not stale" to keep this issue open!

As a friendly reminder: the best way to see this issue, or any other, fixed is to open a Pull Request. Check out gatsby.dev/contributefor more information about opening PRs, triaging issues, and contributing!

Thanks for being a part of the Gatsby community! 💪💜

[gatsbot[bot]]

Hey again!

It’s been 30 days since anything happened on this issue, so our friendly neighborhood robot (that’s me!) is going to close it.

Please keep in mind that I’m only a robot, so if I’ve closed this issue in error, I’m HUMAN_EMOTION_SORRY. Please feel free to reopen this issue or create a new one if you need anything else.

As a friendly reminder: the best way to see this issue, or any other, fixed is to open a Pull Request. Check out gatsby.dev/contribute for more information about opening PRs, triaging issues, and contributing!

Thanks again for being part of the Gatsby community!

[shinebayar-g]

Any plan to support ?rest_routeURL? as others said its more reliable endpoint if one doesn't use pretty urls

[cjhaviland]

@shinebayar-g I guess I should take another serious look at the changes I made. As far as I could tell it doesn't _seem_ difficult based on how I did it. I'll see if I can actually build the files and test though. Then maybe we can get someone to re-open this ticket and I can do a pull request.

[fwielstra]

Can this issue be looked into again? We're running Wordpress as purely a rest api, in that use case adding pretty URLs doesn't make a lot of sense. I can only find two instances of wp-json in https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby-source-wordpress/src/fetch.js but I'm not sure if there's any subtleties in there I'm missing.

[magicink]

@wardpeet The assumption that wp-json is the WordPress default might be incorrect. As other have noted above, using the parameter rest_route is the actual WordPress default as it is available with or without pretty permalinks (wp-json is only accessible with pretty permalinks). I have a fork branch which would allow wp-json to continue to be used as the default value, but it its used, it uses the rest_route parameter instead.

https://github.com/magicink/gatsby/blob/627a6cbd1bade30435b59913e405b9023c078abf/packages/gatsby-source-wordpress/src/fetch.js#L277-L290

    let restRoute = url;
  if (url.includes('/wp-json/')) {
    restRoute = url.replace('/wp-json', '/?rest_route=');
  }


  let routeResponse = await getPages({
    url: restRoute,
    _perPage,
    _auth,
    _cookies,
    _accessToken,
    _verbose,
    _concurrentRequests,
  })

The other issue is that getPages always prepends ?, which is the real reason you can just slap ?rest_route= as the value for restApiRoutePrefix.

https://github.com/magicink/gatsby/blob/627a6cbd1bade30435b59913e405b9023c078abf/packages/gatsby-source-wordpress/src/fetch.js#L402-L405

    const getOptions = page => {
      let o = {
        method: `get`,
        url: `${url.includes('?rest_route=') ? `${url}&` : `${url}?`}${querystring.stringify({
          per_page: _perPage,
          page: page,
        })}`,
      }

This "works" but I think a new option called useRestRouteParameter at the config level is more elegant, anyway I'm open to your thoughts on the matter.

[robations]

It seems to me like ?rest_route= would be a better default (ignoring potential BC issues). Perhaps an update could detect whether ? is in the restApiRoutePrefix and behave accordingly?

edit: oh, I see @magicink this is more or less what you've done.

[robinmetral]

I'll reopen this issue because it's obviously still affecting people.

@magicink I agree that a plugin option like useRestRouteParameter would be cleaner and ensures that there would be no regressions. If ?rest_route is more common than wp-json, the option could possibly be true by default and set to false for users using pretty permalinks.

On the other hand, adding an option exposes this setting to plugin users, and I'm not sure that it should be (users shouldn't have to care about pretty permalinks or not, especially when using WP as a headless CMS).

I think a PR could actually be open if anyone feels like it, the implementation details will be easier to discuss over there.

[TylerBarnes]

Hey everyone, thanks for your comments, thoughts and debugging on this.
We will soon be sunsetting our usage of the WP REST API in favour of using WPGraphQL in v4. We're currently working on an alpha (moving to beta within a couple weeks) of that next major version. I'd highly recommend upgrading as this will no longer be a problem in v4 (https://github.com/gatsbyjs/gatsby-source-wordpress-experimental).
You can see some reasons on why it's a good idea to upgrade here and some notes on how to migrate here.

For this reason, I don't believe it's worth fixing this issue as v3 will soon be deprecated. However, if anyone would like to contribute a PR we can get that merged before v4.

Thanks!