API V2 content controller separation

[kirrg001]

I see some good reasons why we should separate the controllers for the content API.

1. You don't have a limited access if the controllers are generic. For example: the V2 content API allows the theme developer to fetch "authors" {{#get "authors"}}. The get helper requires the target API version (require(.../api/).v2), but we require all of the controllers. That means we either need to disallow this behaviour in the helper level, so that you can't do {{#get "users"}}, which is very hard to maintain or the API returns just a set of controllers you can use for the content API.

2. Admin controllers allow more than content controllers. e.g. the users controller allows to fetch roles & permissions. In v0.1 there was one controller who just allowed all the includes (roles, permissions, couting posts) and the model layer had added this condition. to avoid that a public access can fetch roles. This is very hard to maintain and it's IMO not the correct approach. If we would separate the controllers, we could just allow that the content user controller can fetch count.posts, nothing more.

3. We always need to take care that we do a correct differentiation between content and admin access e.g. in serializers.

4. Imagine you want to develop both API's separately. You can't. Because they both use the same controller base.

I can imagine if we separate both, we can optimise the API frame step by step to avoid having too many duplicate code.

• Fixed apiType and broken error handling #10536 (comment)

[naz]

As model separation is introduced with #10124, there has surfaced a need to separate tags controller for tags model used in public context. Wanted to discuss a folder structure for new controllers that are only meant to be used by the Content API.

Would it make sense to divide v2 controllers to a structure similar to the one used in routes /web/api/v2/(admih|content)? The reason for this would be to avoid naming controllers in the same folder like tagsPublic or postsPublic if such controllers are introduced in the future.

[kirrg001]

Would it make sense to divide v2 controllers to a structure similar to the one used in routes /web/api/v2/(admih|content)

Yes makes sense to me 👍

[kirrg001]

State of this issue

API v2 fully separated the Admin & Content controllers.

• pagesPublic -> /content/pages
• postsPublic -> /content/posts
• tagsPublic -> /content/tags
• settingsPublic -> /content/settings
• authorsPublic -> /content/authors

The rest of the controllers belong to the Admin API. This was a first good step into the right direction.

Further or existing problems

• (1) is not solved yet
• (3) is not solved yet
• If you require the API, you get all Content & Admin API controllers, but you need to know that api.postsPublic is the Content API implementation (specific knowledge)

Options

Option 1

We could create api/v2/content and api/v2/admin and keep the current structure (e.g. from api/v2/utils/validators/ to api/v2/content/utils/validators).

See a working prototype on Github.

Adavantages:

• Solves (1) and (3)
• The pipeline & stages implemention doesn't need a refactoring
• e.g. Apps could only get access to the Content API

Challenges:

• We need to take care that the "shared" implementation must be valid for Content & Admin API requests, which it is currently.
• Dynamic routing needs to require the Content API. Some bit's need to be refactored out e.g. this piece. Would need to collect more places.
• We need to handle a lot more code and files. We already have many files inside the API layer.
• API v2 Content & Admin implementation would need to share a lot of logic e.g. url decoration etc. We would need a shared folder for both (e.g. api/v2/shared). Increases complexity.
• Refactoring should only happen when we've dropped v0.1, because e.g. dynamic routing is generic and API v0.1 has no concept of a content and admin API folder. Otherwise we would need to support a controller configuration per API version with folders e.g. from postsPublic -> content.postsPublic.

Option 2

Leave as is and improve what we have to get rid of the problems e.g. which controllers the theme helpers can access.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.