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: Create/Update/Delete (POST/PATCH/DELETE) ConfigEntity via REST

Documentation links

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: 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: Serialize file content (base64) to support REST GET/POST/PATCH on file entity

More general issues

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

Proposed resolution

Remaining tasks

User interface changes

API changes

Comments

clemens.tolboom’s picture

Issue summary: View changes

Fixed some links and made some lists. Still needs some edits.

clemens.tolboom’s picture

Issue summary: View changes
clemens.tolboom’s picture

Issue summary: View changes
clemens.tolboom’s picture

Issue summary: View changes

New issue is about output format. Everything seems to be a string.

#2336741: Rest request does not contain raw values for ie boolean and number

clemens.tolboom’s picture

clemens.tolboom’s picture

Issue summary: View changes
dawehner’s picture

clemens.tolboom’s picture

Issue summary: View changes
clemens.tolboom’s picture

Issue summary: View changes

Fixed bad link.
Added link to #2343431: Make JSON data non-Drupalish

Andre-B’s picture

will be in amsterdam, count me in for the sprint if you like.

clemens.tolboom’s picture

Issue summary: View changes

@Andre-B cool :-)

Please check the sprint schedule through https://groups.drupal.org/node/427578

Andre-B’s picture

@clemens.tolboom already did ;) when will you be there?

clemens.tolboom’s picture

Issue summary: View changes
Issue tags: +Amsterdam2014
clemens.tolboom’s picture

Issue summary: View changes

Added authentication section to be triaged later.

clemens.tolboom’s picture

clemens.tolboom’s picture

Issue summary: View changes
Related issues: +#1869548: Opt-in CORS support
clemens.tolboom’s picture

Issue summary: View changes
clemens.tolboom’s picture

Issue summary: View changes
Issue tags: -Amsterdam2014
clemens.tolboom’s picture

clemens.tolboom’s picture

Issue summary: View changes

Removed sprint reference from Amsterdam. And serializer is a module again.

clemens.tolboom’s picture

Issue summary: View changes

Typos

Wim Leers’s picture

Category: Task » Plan
Status: Active » Postponed (maintainer needs more info)
Issue tags: +Needs issue summary update

Do we still want to keep this? If we do, we need to update the IS.

clemens.tolboom’s picture

Version: 8.0.x-dev » 8.1.x-dev

@WimLeers what summary update you need?

When I find time to get to the issues I move here. But not much followers have contributed so not sure we need this open. Feel free to close.

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

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

clemens.tolboom’s picture

Just ran into translation problems for a bilingual CKEditor plugin to discover this issue has no section about it. #2135829: EntityResource: translations support and views #2664880: DataEntityRow doesn't respect translations

clemens.tolboom’s picture

Issue summary: View changes
clemens.tolboom’s picture

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.

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

Drupal 8.3.0-alpha1 will be released the week of January 30, 2017, which means new developments and disruptive changes should now be targeted against the 8.4.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

klausi’s picture

Status: Postponed (maintainer needs more info) » Closed (outdated)

I think this has been sufficiently covered in other issues, feel free to reopen if we forgot something.