[RFC] Subresource metadata

[soyuka]

This issue merges multiple subresources issues because the root problem is the same.

While talking with core members at EU-FOSSA Hackathon we came to a solution. Best would be to refactor the ApiSubresource annotation so that it supports the same attributes as does the ApiResource. For example:

• routing options
• access_control
• normalization context

Thanks to this it'll be easier to declare these and we solve the issue (mentioned in #1617 (comment)). The subresource metadata will not be in ApiResource anymore but directly inside the ApiSubresource annotation.

Todo list :

• Fix swagger and don't show the collection on the side that doesn't own the Subresource ([Swagger] Do not tag a sub-resource operation with child resource #1612)
• Fix the serialization context declaration (solves [Subresource] Fixed the serialization context builder #1617 and (de)normalization_context is not used for subresourceOperations #1616 and improves DX for SubResource and security #1649)
• Simplified the code for the documentation (ses Subresource collection filters not added by DocumentationNormalizer #1736)
• Subresource operations may override collection operations which should not happend (see @ApiSubresource route overriding other collection routes with same path api-platform#1022)

consider: #3466 and work on #3689
Maybe that this is a prerequisite for write support on subresources (see #2598 #2428)

ping @torreytsui @vincentchalamon please lmk if I forgot things
@lyrixx I'm closing related PRs we will definitely take back the work you did if we can, thanks for pushing this issues

[lyrixx]

Very good move! Can't wait to have it land in APIP 👍

[Devristo]

Would this RFC also help creating custom subresources as described in #1654?

[teohhanhui]

Fix swagger and don't show the collection on the side that doesn't own the Subresource

I disagree. We could show subresource operations in a separate subsection, maybe? (Not sure if possible with Swagger UI.)

[dunglas]

Not sure if possible with Swagger UI.

AFAIR we tried and it’s not.

[teohhanhui]

To answer my own question:

OAI/OpenAPI-Specification#1367
swagger-api/swagger-ui#2129

So, nope.

[teohhanhui]

An alternative is to tag them as e.g. Question (subresource)?

EDIT: Never mind, I think the suggestion in the original issue is better indeed. Just tag it from the root resource it could be accessed from. But perhaps the operation's description could be improved?

[torreytsui]

I think tagging on the root resource seems the best option we have so far. My thought is that subresource no matter how deep is it (/foos/1/bars/1/bazs/1/quxs/...), it starts with the root and the user will have to be aware of it and also consider it.

Fix the serialization context declaration

Should all levels configure in root (i.e., foo below) or spread into each level (i.e., foo configure bar, and bar configure baz)?

• /foos/1/bars/1/bazs
• /foos/1/bars/1/bazs/1
• /foos/1/bars/1

Each of above are different operations and it makes sense to have their own independent configurations. How do we explicitly declare them?

How to enable / disable certain operations? At the moment, there are only item GET and collection GET, but when we implement write operations, it will get complicated and escalate as the depth grows.

[GregoireHebert]

Subresource operations may override collection operations which should not happen (see api-platform/api-platform#1022)
This does not seems to be the case anymore.

[GregoireHebert]

Fix swagger and don't show the collection on the side that doesn't own the Subresource (#1612)
Seems to be fixed too.

[GregoireHebert]

#1616 is fixed in #3690

[GregoireHebert]

I think this could be closed in favour of #3689

[brunonic]

swagger_context is still not supported under subresource operation ? #1873

[vincentchalamon]

Subresources have been deprecated in 2.7 and removed in 3.0

[gigo6000]

Subresources have been deprecated in 2.7 and removed in 3.0

@vincentchalamon Is this still valid? I see a Subresources section in the latest documentation (v3.1): https://api-platform.com/docs/core/subresources/

[vincentchalamon]

@gigo6000 the ApiSubresource has been deprecated in 2.7 and removed in 3.0. The notion of Subresource is still active as everything is an ApiResource now