Documentation: REST resource uses a different URI path for POST than for GET|PATCH|DELETE

Can you try to post to /todo_rest_resource ?
$create_path = isset($definition['uri_paths']['https://www.drupal.org/link-relations/create']) ? $definition['uri_paths']['https://www.drupal.org/link-relations/create'] : '/' . strtr($this->pluginId, ':', '/'); is the line that creates the needed route.

#2800871: Create a post method in Drupal 8: how to receive data? shows you can you use a different path for the POST route.

Well, its easy, GET/PATCH/HEAD ... all deal with a canonical URL, like the url to the entity you are saving. This one doesn't exist yet for newly created entities, which is the purpose of a POST request. Given that we need two different paths for them.

#2293697: EntityResource POST routes all use the confusing default: use entity types' https://www.drupal.org/link-relations/create link template if available is related — it makes this sensible/logical for Entity REST resources.

To answer #6: Yes, in all cases it uses the "canonical path", and only in the POST case, it uses the "create path". You're saying the path is explicitly set to the plugin ID, but this is not true.

Look at the code:

    $canonical_path = isset($definition['uri_paths']['canonical']) ? $definition['uri_paths']['canonical'] : '/' . strtr($this->pluginId, ':', '/') . '/{id}';
    $create_path = isset($definition['uri_paths']['https://www.drupal.org/link-relations/create']) ? $definition['uri_paths']['https://www.drupal.org/link-relations/create'] : '/' . strtr($this->pluginId, ':', '/');

    …

    foreach ($methods as $method) {
      $route = $this->getBaseRoute($canonical_path, $method);

      switch ($method) {
        case 'POST':
          $route->setPath($create_path);
          …
          break;

        case 'PATCH':
          …
          break;

        case 'GET':
        case 'HEAD':
          …
          break;

        default:
          …
          break;
      }
    }

In other words:

1. we default the REST resource's route's path to the canonical path
2. but for POST, we override it: $route->setPath($create_path
3. and the default canonical & create paths are both based on the plugin ID. The default canonical path is /{plugin_id}/{resource_id}, the default create path is /{plugin_id}

So, as long as you don't specify a canonical path, all URLs will make sense. But … you did specify a canonical path:

 *   uri_paths = {
 *     “canonical” = “/todo”
 *   }

So, if you want your "create path" (POST) to match, then you need to change that to:

 *   uri_paths = {
 *     “canonical” = “/todo”
 *     "https://www.drupal.org/link-relations/create" = "/todo"
 *   }

Also: your canonical path looks incorrect, because it doesn't allow for an ID to be specified. It should probably be /todo/{todo_id}. So you probably want something like:

 *   uri_paths = {
 *     “canonical” = “/todo/{todo_id}”
 *     "https://www.drupal.org/link-relations/create" = "/todo"
 *   }

I trust/hope this answers all your questions. Thanks for reporting this!

So, I don't there is a bug in the code here. But, what clearly is lacking, is documentation. So, tagging for that, and working on that.

Documentation written: https://www.drupal.org/node/2667736/revisions/view/9913841/10076979 — see the bottom of https://www.drupal.org/developing/api/8/rest.

You're very welcome! Glad you're happy with this solution :)

Did this change in D9? Do we need to update the docs again?

in Drupal 9, the create link for POST operations has changed, as seen in ResourceBase.php

public function routes() {
    $collection = new RouteCollection();

    $definition = $this->getPluginDefinition();
    $canonical_path = isset($definition['uri_paths']['canonical']) ? $definition['uri_paths']['canonical'] : '/' . strtr($this->pluginId, ':', '/') . '/{id}';
    $create_path = isset($definition['uri_paths']['create']) ? $definition['uri_paths']['create'] : '/' . strtr($this->pluginId, ':', '/');

    $route_name = strtr($this->pluginId, ':', '.');

    $methods = $this->availableMethods();
    foreach ($methods as $method) {
      $path = $method === 'POST'
        ? $create_path
        : $canonical_path;
      $route = $this->getBaseRoute($path, $method);

      // Note that '_format' and '_content_type_format' route requirements are
      // added in ResourceRoutes::getRoutesForResourceConfig().
      $collection->add("$route_name.$method", $route);
    }

    return $collection;
  }

In order to get the correct uri for POST commands, now in the @RestResource annotation, in uri_paths, the key "create" has to be used referring to the uri - similar to the approach for the canonical uri.

I think the public documentation has to be updated as well along with API documentation for Drupal 9. Couldn't find a reference to the change from

https://www.drupal.org/docs/drupal-apis/restful-web-services-api/restful...
https://api.drupal.org/api/drupal/core%21core.api.php/group/third_party/...
https://api.drupal.org/api/drupal/core%21modules%21rest%21src%21Annotati...

Not exactly sure where to document this change.