[meta] REST et al

Problem/Motivation

This issue tries to provide an overview of current state of REST, HAL and it's issues.

See especially #2721489: REST: top priorities for Drupal 8.2.x

Whenever REST is named it is about the rest.module or a json request.
Whenever HAL is named it is about the hal.module or hal+json request.

Other parts are modules serializer file and views.

@WimLeers has prioritised issues by title prefix: PP-# which means postponed-level. So to move stuff forward hunt for PP or PP-1 issues and their blocking issues

Current Open issues

Below are the parts providing HAL and REST from a REST client perspective.

How to use HAL or REST

There is a lot of noise on how to use HAL or REST. What operation supports either json and/or hal+json? What is the state of the current documentation?

#2282603: How to get image and term data populated in a REST JSON response?
#2300677: JSON:API POST/PATCH support for fully validatable config entities

Documentation links

• https://api.drupal.org/api/drupal/core!modules!system!core.api.php/group...
• https://www.drupal.org/documentation/modules/rest
• https://www.drupal.org/documentation/modules/hal
• https://www.drupal.org/documentation/modules/serialization
• /admin/help/rest
• /admin/help/hal

REST API documentation

1. We should provide the possibility to generate the API documentation.
2. We need a mechanism to provide the current version of the API. A site update or adding entities or collections (views) needs a way to announce this changed API.
3. We cannot provide 2 different API versions by design.

#1925618: Ensure Drupal's web services are self-documenting: Swagger support OR rest_api_doc to Drupal core as an experimental module?
#2239333: Restful web services need to have version prefix URI for entities

REST API

We have a weird interface to our content. Most APIs connect to their content type like article or post (aka Drupals bundle) instead of entity-type like node, comment or user. This causes a mismatch between rest permissions and entity+bundle access permissions too.

#2342165: Permissions for REST and entities are not aligned

#2293697: EntityResource POST routes all use the confusing default: use entity types' https://www.drupal.org/link-relations/create link template if available
#2304849: Stop excluding local ID and revision fields from HAL output

#2472321: Move rest.module routes to /api

CORS

#1869548: Opt-in CORS support

Authentication

This can be through core cookie and basic auth in core. There is contrib oauth.

#2403307: RPC endpoints for user authentication: log in, check login status, log out

Translations

#2135829: [PP-1] EntityResource: translations support
#2664880: DataEntityRow doesn't respect translations

Permissions

The REST access are not in line with the user permissions. Being able to post on /node (rest permission create node) can be blocked by missing ‘create article` permission.

#2342165: Permissions for REST and entities are not aligned

Operations

It’s not clear what operation are allowed for REST request versus HAL request.

REST should support GET, POST, DELETE which is not yet confirmed or documented.

HAL should support GET, POST, PATCH, DELETE

#1869548: Opt-in CORS support
#2274153: Make RESTTestBase::httpRequest() work with HEAD requests

Views

BASIC_AUTH is broken and needs #2228141: Add authentication support to REST views

One can create a Rest export display.

#2336741: Rest request does not contain raw values for ie boolean and number
#2344151: Comment field access doesn't work if $items isn't present

In HAL these are called collections.

#2100637: REST views: add special handling for collections

Fields

The serializer supports field access but there is no display mode to filter out fields.

#2339795: Add "REST modes", just like we have "view modes" and "form modes" AND depth argument to reduce # of requests
#2343431: Make JSON data non-Drupalish

File

File is not a first-class entity yet. It lacks permissions, listing, CRUD pages. Should it be contrib or core. See https://www.drupal.org/project/file_entity

#2310307: File needs CRUD permissions to make REST work on entity/file/{id}

We currently want upload files as BASE64 encoded field value. Why? This seems not being explained and is not in line with other REST APIs. The workflow on ie https://developers.facebook.com/docs/php/howto/uploadphoto/4.0.0 is to ‘multipart’ post a file and use the resulting ID for further processing. They us http://php.net/manual/en/class.curlfile.php

#1927648: Allow creation of file entities from binary data via REST requests

More general issues

#2259445: Entity Resource unification
#2281645: Make entity annotations use link templates instead of route names #7

Proposed resolution

Remaining tasks

User interface changes

API changes