At today's meeting of our local Drupal group, someone brought up the subject of REST. So, we went and found the REST documentation on drupal.org. It is supposed to give you some background as well as practical information you would need to know in order to use Drupal 8's built-in REST services, but it has some serious flaws, and needs an update:

a) We started here:
https://www.drupal.org/docs/8/core/modules/rest/overview
One major problem with this page is that it assumes you know what "resources" are. This is not explained anywhere.

b) Next we went here:
https://www.drupal.org/docs/8/core/modules/rest/1-getting-started-rest-c...

Right at the top of that page, it says "Go read this other page", so that took us to
https://www.drupal.org/docs/8/api/restful-web-services-api/restful-web-s...

However, the header on that page says for basic information to go back to the page we just came from. Oops! They can't both be read first!

c) After reading that "go to" page, I didn't know any of the things that I was supposed to learn.

So... I think we really need a new page that explains the basics? Or something. Anyway, I couldn't make much sense of the documentation on these 3 pages. The terminology is never explained, and although I know a lot about Drupal 8, I couldn't follow this documentation.

Comments

jhodgdon created an issue.