I spent last week triaging the REST module issue queue, to identify the top priorities for REST to support all use cases, and to be less painful to use. This is what I came up with.

Any use case (fully decoupled, progressively decoupled, content sync)

  1. Impossible to update Comment entity with REST: #2631774: Impossible to update Comment entity with REST (HTTP PATCH): bundle field not allowed to be updated, but EntityNormalizer::denormalize() requires it
  2. Basic config entity support: #2724823: EntityResource: read-only (GET) support for configuration entities
  3. EntityResource: translations support: #2135829: EntityResource: translations support
  4. File uploads: #1927648: Serialize file content (base64) to support REST GET/POST/PATCH on file entity
  5. Full config entity support: #2300677: [PP-2] Create/Update/Delete (POST/PATCH/DELETE) ConfigEntity via REST
  6. REST export entity views supporting translations: #2664880: DataEntityRow doesn't respect translations
  7. Pagination support: #2100637: Add special handling for collections in REST
  8. REST export views supporting pagination: #2099281: [PP-1] REST views: pagination link relations
  9. REST export views break the HTML view if they're on the same path: #2730497: REST Views override existing REST routes + #2772537: REST Views override existing REST GET routes + #2449143: REST views specify HTML as a possible request format, so if there is a "regular" HTML view on the same path, it will serve JSON
  10. REST export views: row-level caching: #2648268: REST views: row-level caching doesn't exist, unlike for other types of views
  11. REST export views: authentication support: #2228141: Add authentication support to REST views
  12. HEAD requests do not work: #2752325: Automatically provide HEAD support when a REST resource supports GET

Fully decoupled

  1. Logging in: #2403307: RPC endpoints for user authentication: log in, check login status, log out
  2. Registering: #2291055: REST resources for anonymous users: register
  3. CORS (to put D8 on different domain): #1869548: Opt-in CORS support

DX

  1. Content-Type request header missing: #2659070: REST requests without Content-Type header: unhelpful response significantly hinders DX, should receive a 415 response
  2. X-CSRF-Token request header missing: #2681911: REST requests without X-CSRF-Token header: unhelpful response significantly hinders DX, should receive a 401 response
  3. GET/PATCH/DELETE to /node, but POST to /entity/node: #2293697: EntityResource POST routes all use the confusing default: use entity types' https://www.drupal.org/link-relations/create link template if available
  4. Configuring REST is a PITA: #2308745: Remove rest.settings.yml, use rest_resource config entities
  5. Configuring REST permissions is a PITA: #2664780: Remove REST's resource- and verb-specific permissions for EntityResource, but provide BC and document why it's necessary for other resources
  6. Simplify REST configuration: #2721595: Simplify REST configuration

General reliability, maintainability & DX

#2737719: EntityResource: Provide comprehensive test coverage: for every entity type, every format, every method — this actually relates to many of the above issues, and would provide much, much stronger assurances that REST works as expected & intended.

Comments

Wim Leers created an issue. See original summary.

Wim Leers’s picture

Issue summary: View changes

One down :)

dawehner’s picture

Issue summary: View changes
Related issues: +#2631774: Impossible to update Comment entity with REST (HTTP PATCH): bundle field not allowed to be updated, but EntityNormalizer::denormalize() requires it, +#2300677: [PP-2] Create/Update/Delete (POST/PATCH/DELETE) ConfigEntity via REST, +#2135829: EntityResource: translations support, +#1927648: Serialize file content (base64) to support REST GET/POST/PATCH on file entity, +#2664880: DataEntityRow doesn't respect translations, +#2100637: Add special handling for collections in REST, +#2099281: [PP-1] REST views: pagination link relations, +#2449143: REST views specify HTML as a possible request format, so if there is a "regular" HTML view on the same path, it will serve JSON, +#2648268: REST views: row-level caching doesn't exist, unlike for other types of views, +#2403307: RPC endpoints for user authentication: log in, check login status, log out, +#2291055: REST resources for anonymous users: register, +#1869548: Opt-in CORS support, +#2681911: REST requests without X-CSRF-Token header: unhelpful response significantly hinders DX, should receive a 401 response, +#2293697: EntityResource POST routes all use the confusing default: use entity types' https://www.drupal.org/link-relations/create link template if available, +#2308745: Remove rest.settings.yml, use rest_resource config entities, +#2664780: Remove REST's resource- and verb-specific permissions for EntityResource, but provide BC and document why it's necessary for other resources

Added another issue which could be interesting: #2721595: Simplify REST configuration

aneek’s picture

Wim Leers’s picture

#4I don't consider that a top priority: it's an edge case. Everything listed in the top priorities is a huge problem/gap. Don't worry, it will get fixed. I moved it to the rest.module component for better visibility, so we don't forget about it.

marthinal’s picture

@Wim IMHO #2310307: File needs CRUD permissions to make REST work on entity/file/{id} would be a critical issue here if we want to upload files. AFAIK we want to create 2 entities in the same request and avoid to create the File and then the node(or the custom entity). @alexpott told me that we want to avoid the current solution("everybody can upload files").

And #1927648: Serialize file content (base64) to support REST GET/POST/PATCH on file entity uses this patch...

dawehner’s picture

Issue summary: View changes
dawehner’s picture

Wim Leers’s picture

Issue summary: View changes
Related issues:
Wim Leers’s picture

Wim Leers’s picture

Wim Leers’s picture

Issue summary: View changes

Yay, #2631774: Impossible to update Comment entity with REST (HTTP PATCH): bundle field not allowed to be updated, but EntityNormalizer::denormalize() requires it landed! The highest priority issue, because it literally made REST broken/impossible to use for many use cases!

Wim Leers’s picture

Issue summary: View changes

Clarify the different levels of config entity support.

Wim Leers’s picture

Wim Leers’s picture

Wim Leers’s picture

Wim Leers’s picture

Wim Leers’s picture

larowlan’s picture

tedbow’s picture

dawehner’s picture

#2113345: Define a mechanism for custom link relationships is an issue someone could review. If someone needs something special: #1928868: Typed config incorrectly implements Typed Data interfaces is up there for review. This will enable POST/PATCH of config entities.

Especially the later would be nice because we need probably a full release to add the required constrains so we can start supporting updates.

Wim Leers’s picture

#21: thanks for that! I mostly agree. There are two things where I disagree:

  1. #1869548: Opt-in CORS support is also very close. It just needs documentation to be written and one fairly minor change. Working on the documentation for that now.
  2. #2664780: Remove REST's resource- and verb-specific permissions for EntityResource, but provide BC and document why it's necessary for other resources was actually RTBC… but then it turned out that it was really blocked on #2662284: Return complete entity after successful PATCH, which itself is also super super close.

So: +1 for attempting to land the following in the next few weeks:

  1. #2753681: Move CSRF header token out of REST module so that user module can use it, as well as any contrib module
  2. #2403307: RPC endpoints for user authentication: log in, check login status, log out
  3. #2291055: REST resources for anonymous users: register
  4. #1869548: Opt-in CORS support
  5. #2662284: Return complete entity after successful PATCH
  6. #2664780: Remove REST's resource- and verb-specific permissions for EntityResource, but provide BC and document why it's necessary for other resources

You're right that #2737719: EntityResource: Provide comprehensive test coverage: for every entity type, every format, every method can happen after feature freeze. But, of course, it'll mean less clean tests in the ones above. Then again, most of those already have their tests written already anyway. So I think it's fine. #2737719: EntityResource: Provide comprehensive test coverage: for every entity type, every format, every method will put us in a great position to make D8 REST "best-in-class" in 8.3, per #2757967: API-first initiative.


#22: I reviewed #2113345: Define a mechanism for custom link relationships. I can't review #1928868: Typed config incorrectly implements Typed Data interfaces — that needs review from a Typed Data maintainer.

Wim Leers’s picture

dawehner’s picture

I can't review #1928868: Typed config incorrectly implements Typed Data interfaces — that needs review from a Typed Data maintainer.

It almost feels as if noone could review it :)

Wim Leers’s picture

You'll need to bribe a Typed Data maintainer :P

jacov’s picture

jacov’s picture

jacov’s picture

jacov’s picture

Wim Leers’s picture

@jacov: Can you please not mark all of your own issues as "top priorities"? Can you leave that to the people maintaining the module, who are used to triaging incoming issues, and who have a much better understanding of the relations between different issues? Thanks.

dawehner’s picture

@jacov
One thing you always have to keep in mind. Critical in an issue doesn't mean its critical for you, but rather the site. Each major is most likely a critical issue aka. show blocker on actual sites, but we cannot treat Drupal core as a union of sites. This simply doesn't scale.

Wim Leers’s picture

Issue summary: View changes

Apparently @jacov even put all of his top priorities at the very top of each list in the issue summary. I'm sorry, but that's just plain rude.

dawehner’s picture

Thank you @Wim Leers for cleaning up this mess!

Wim Leers’s picture

Wim Leers’s picture

Wim Leers’s picture

Issue summary: View changes

Forgot to update the IS for #36.

Wim Leers’s picture

Title: REST: top priorities » REST: top priorities for Drupal 8.2.x

Let's keep this issue just for Drupal 8.2.x. We can create a new Plan issue for 8.3.x later. That will keep both issues manageable in size, and they'll provide useful reference points in the future.

dawehner’s picture

Good idea. In general there are also things which are pure bug fixes, that can land more or less at any point, and there are more task/featurish things, which should be prioritized in the next 2 weeks.

Wim Leers’s picture

Wim Leers’s picture

Wim Leers’s picture

Issue summary: View changes
dawehner’s picture

Issue summary: View changes

After trying to use the new configuration entity based system, I think we should fix #2777969: Provide an example REST configuration entity

Version: 8.2.x-dev » 8.3.x-dev

Drupal 8.2.0-beta1 was released on August 3, 2016, which means new developments and disruptive changes should now be targeted against the 8.3.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

Wim Leers’s picture

Status: Active » Fixed

Thanks everybody for helping out here!

I'm proud of the progress we've made. We've tackled lots of tricky problems. rest.module is in a much better place now! We fixed the majority of things listed here.

Note that of the 34 issues are tagged with 8.2.0 release notes, 9 are for REST module!, that's more than 25%!

Now it's time to move on to 8.3.x. I've opened #2794263: REST: top priorities for Drupal 8.3.x for that, which is the continuation of this issue.

Finally, I'll still work on getting #2737719: EntityResource: Provide comprehensive test coverage: for every entity type, every format, every method in 8.2, because that's only adding test coverage. It may uncover bugs, but those bugs need to be fixed in 8.2 anyway. If you're planning to use D8.2's REST API, you may want to follow that issue. If you're looking to use D8's REST API later, starting early next year, you may want to follow #2794263: REST: top priorities for Drupal 8.3.x, because 8.3 will be finalized near the end of Q1 2017.

Thanks, and see you around!

Wim Leers’s picture

Issue summary: View changes

Status: Fixed » Closed (fixed)

Automatically closed - issue fixed for 2 weeks with no activity.

Wim Leers’s picture

Project: Drupal core » Drupal core ideas
Version: 8.3.x-dev »
Component: rest.module » Active Initiative