Best Practice for Endpoints using POST to Perform Searches (similar to a GetCollection)

[d42ohpaz]

Our API has the requirement to allow searching for "things" using specific identifiers, which may exceed the max length of the GET query string. Our current implementation uses HTTP POST and sends a JSON data structure with the varying criteria.

From my research so far, I am getting the impression I will need to create a custom HttpOperation to achieve my goal. I wanted to extend the GetCollection and change its method to POST, but that class is final and cannot be extended.

Before I dive too deeply into this rabbit hole, I was looking to get feedback from the community in case this has already been solved, or what the best direction would be to solve this problem myself.

Info:

• Symfony 8.1 application
• API Platform (api-platform/symfony): 4.3.17
• Using application/json or application/ld+json (json preferred)

Examples:
curl -X POST https://api.local/users --json '{"username": ["bobby", "jb1234", "billyjoearmstrong", ...]}'
curl -X POST https://api.local/users --json '{"uniqueId": [123, 456, 789, ...]}'
curl -X POST https://api.local/users --json '{"somethingElse": ["other", "unique", "criteria", ...]}'

Requirements:

1. Stays within the best practices of API Platform (i.e., not using Symfony controllers)
2. Works like the GetCollection and can be re-used across multiple resources
3. Accept a specific data structure shape and can be easily validated
4. Still allow URI variables for filtering and paginating the dataset

Thank you in advance!

[d42ohpaz]

I just found feat: HTTP QUERY method support in the core repo. I will upgrade to 4.4 to see if that gets me where I need to go. I'm still open to best practices and other advice if there is any.

[identity-wael]

For the POST route, you don't need to subclass GetCollection. A custom Post operation with an input DTO and your own processor is an API Platform-native route:

POST /users/search
  → deserialize + validate SearchUsersInput
  → SearchUsersProcessor invokes the search service
  → serialize the result/page DTO

Use input for the validated criteria DTO, an explicit output result DTO and status: 200. Set read: false if you don't want the default state-provider read before processing. Keep the operation's write stage enabled: that's the stage which calls a custom processor for POST, even when your processor only queries data. Selecting your own processor avoids invoking the Doctrine persistence processor.

The official DTO and state processor patterns cover these pieces. A processor can return the search result rather than the input object.

The main caveat is collection behavior: a custom POST doesn't automatically inherit GetCollection's filters, paginator/Hydra response and documentation merely because it returns an array. Make the page/result contract explicit, validate query-string pagination as well as the body, and reuse your search/filter service across resources. Keep resource/tenant authorization inside that query path too.

Your linked HTTP QUERY work may provide a cleaner collection-shaped operation on 4.4, but for clients that must keep POST, the DTO/processor approach avoids depending on that upgrade.