[TASK] Create documentation pages on drupal.org

This playlist can serve as documentation as well. We should probably have a textified version of them https://www.youtube.com/playlist?list=PLZOQ_ZMpYrZsyO-3IstImK1okrpfAjuMZ.

I'm currently working on the page for the filtering syntax.

First draft for the filtering page. I'm writing it in markdown right now, but if the book is set up I can insert it directly into drupal.org ?

@JanLaureys if you share the markdown document it would be easier for someone to review your docs :-)

Thanks for your work!!

@e0ipso. Yeah, I couldn't upload .md files, but I had a sudden realisation that I can just make it into a .txt file.

@JanLaureys can you add the filtering documentation in a child page of the "JSON API" that @gabesullice just created? We can probably iterate on that there.

I added the documentation to change the api prefix and the use of IDs instead of UUIDs https://www.drupal.org/node/2804085

Thanks everyone for your efforts. We have started on a great path!

Added my docs to the filtering page. I'll try reformatting the titles etc. soon. I'll also add some examples for sorting and pagination, and if someone wants to rewrite some of my convoluted sentences, feel free :).

For better discoverability of the documentation page I suggest to list the documentation page from the project's page. Projects only can have one documentation link, but we may use the 'Demo' link and/or cross-link from d.o page to video.

That was a great suggestion @Sutharsan. That should be linked now.

Huge thanks to @Sutharsan for creating the documentation in https://www.drupal.org/node/2806567.

If you're creating documentation, writing blog posts, recording videos, etc. Please leave a trace here and we'll find a way to highlight all your contributions!

We probably need some documentation on how to disable specific resources: see #2781459: [FEATURE] Allow disabling resources.

I updated the link in the _help hook :)

As the project page is pimped up and references to both https://www.drupal.org/docs/8/modules/json-api/json-api and the Youtube video is this task still open or can it be closed?

#18 is now for https://www.drupal.org/project/jsonapi_extras I guess which is mentioned on the project page.

#19
@JanLaureys you better place your patch in a separate issue then with needs review I guess.

I found this module the other day while working on a prototype. As someone completely new to this project & decoupled Drupal sites, here's my 2 cents in case it helps your documentation with other people who are very new. Overall I thought the YouTube videos & documentation are already better than 99% of other Drupal modules. It would be nice to see some more concrete examples though. As a new person, here's what the path I took.

I use the Paragraphs module & it seems this is a very common approach to decoupled sites. It seems silly now but it took me a while to realize that including content from the paragraphs was as easy as querying the node I wanted & adding ?include={name_of_field_in_node_that_uses_paragraphs}

Querying individual paragraphs also took a little bit of time. I know realize I can query a paragraph by using /jsonapi/paragraph/paragraph_type/id

Based on my knowledge of how to query paragraphs, I tried to apply this to Drupal menus. Unfortunately the same logic didn't work to query a menu. Querying menus would be great to see added to the documentation. After that, I feel like I could make a decoupled website fairly quick with just the JSON API.

Just another kudos, as I've tried the other API modules Drupal offers in the core. This one was a lot simpler & better than all of them. It's saving me from creating a lot of views & making a lot of XHR requests from JavaScript.

@mattferderer thank for you feedback.

Testing with your mentioned

I tried to apply this to Drupal menus. Unfortunately the same logic didn't work to query a menu. Querying menus would be great to see added to the documentation.

I checked the documentation page https://www.drupal.org/node/2806623 which does not mentions config entities and how to use them. So I added an example to it. Please review.

If you want to follow the CRUD on Config entities #2300677: JSON:API POST/PATCH support for fully validatable config entities is a good starting point.

Thanks @clemens.tolboom. The extra documentation is helpful. My guess is most beginners are just looking to read data so that works perfectly!

Just out of curiosity, when you query the menu do you get any of the menu links back? I just get some basic info about the menu but not the structure. I apologize if this should be a separate issue.

@mattferderer the menu links are not loaded as part of nodes. That is a known (debatable) Drupal behavior. Is that what you are experiencing?

Yep, that is @e0ipso. After some research I came to that conclusion as well. Looks like some other modules have been created to help with that though. I'm using the Rest menu items module & they just added the UUID field in their response. Using that should integrate well with the JSON API to overcome this.

Please vote on #2892600: Add module category 'Decoupled', 'API First', 'Rest' or 'headless'.

@mattferderer full links help more :-p

- https://www.drupal.org/project/rest_menu_items
- https://www.drupal.org/project/rest_menu_tree

@e0ipso the patch from #19 didn't popped up I guess? It is a useful change right?

We should close this issue if possible.

Hmmm .... the documentation page https://www.drupal.org/docs/8/modules/json-api/json-api states

If you feel something should be included in this documentation, but do not have the know-how or expertise to add them yourself, development of this documentation is being tracked in this issue: #2798817: [TASK] Create documentation pages on drupal.org

What should we do? Close this issue or keep it open indefinitely?

Seems like https://www.drupal.org/docs/8/modules/json-api/json-api is pretty well fleshed out, and has been for many months. No need to keep this issue open.

EDIT: and most importantly, it's linked from https://www.drupal.org/project/jsonapi, so it's discoverable!