Add create cqrs endpoint doc

[tleon]

Questions	Answers
Branch?	9.x
Description?	Add documentation for creating a new endpoint using CQRS
Fixed ticket?	Fixes #39179

[kpodemski]

I wanted to deep-dive into the review, but, in my eyes, this piece of content you created is a mix of an article for BuildBlog and actual documentation. It's good! But it could use some improvements and changes to better fit into the docs.

I'm sharing with you my observations and thoughts. I know this article will also be reviewed by @cnavarro-prestashop and @jolelievre, so I'll let them decide on how to proceed.

1. We should help devs understand how CQRS works in PrestaShop, and we do have a documentation for that (https://devdocs.prestashop-project.org/9/development/architecture/domain/cqrs/), unfortunately, I'm not sure to what extent it is up-to-date :(
2. I think that in certain areas of this guide, we lack a clear explanation of why we should do things the way we do. ApiResourceMapping, gridDataFactory, and filtersMapping will all raise questions.
3. The metadata used (CQRSCreate, etc.) comes out of nowhere unless someone reverse-engineers their meaning. We don't need to be super detailed about those, maybe link to the source on GitHub. Again, we have some docs ready to explain better how the API works under the hood, so perhaps it's better to link to the existing resources (https://devdocs.prestashop-project.org/9/admin-api/resource_server/api-platform/).
4. Should we, and when, add unit tests apart from integration ones? And an extra question: will they be required from community contributors?
5. Naming convention could be linked to https://github.com/PrestaShop/ADR/blob/master/0023-cqrs-api-guidelines.md
6. There's a mix in the naming. In the tests, you have /attributes/group

[kpodemski]

Suggested change

	title: Create a new endpoint using CQRS
	title: Creating a new resources using CQRS

[kpodemski]

While we ask contributors to add endpoints, I think this guide is more about adding new resources, right?

So, I think it should be something like:

Creating a new Admin API resource using CQRS

Maybe this statement below could help people understand the concept a bit better?

In the context of PrestaShop's Admin API, each resource corresponds to one or more HTTP endpoints that support CRUD operations.

[kpodemski]

Suggested change

	menuTitle: New CQRS endpoint
	menuTitle: Creating CQRS endpoints

[kpodemski]

This could use a little more context on why the endpoints are part of the ps_apiresources module, what are the benefits, and mention that adding a new endpoint mean contributing/sending a pull request to this module.

The documentation should not focus on creating a pull request, it should focus on how the new endpoints are created. This will better fit documentation than a "how to contribute" piece of content that's better for build.prestashop-project.org.

[Progi1984]

Suggested change

	title: Create a new endpoint using CQRS
	title: Contribute to Core API endpoints using CQRS

[kpodemski]

Original title is better for a developer documentation.

[Progi1984]

We just discuss about it in meeting with @jolelievre. It's confusing bcz with "Create a new endpoint using CQRS", people will believe they can create a new endpoint on their shop, not contribute to Core endpoints.

But I let @jolelievre & you decide.

[kpodemski]

Hmmm, ok, makes sense.

We definitely need both, a way for users to know how to add a new endpoint for themselves and to the core.

I'd say that for now we can change it, but later it would be wise to split this doc or add another chapter on how to make custom module as a provider for resources - @jolelievre would that work?

[jolelievre]

Yep why not, we have a small section and example modules for that:

• https://devdocs.prestashop-project.org/9/admin-api/how-to-use/#extending-api
• https://github.com/PrestaShop/example-modules/tree/master/api_module

If there is a need for additional doc I'm always okay with it. But I won't be the one writing it next time 😅