HTTP Search APIs that use the HTTP POST method typically handle complex queries by receiving data in the request body rather than the URL. This approach supports advanced search functionalities, including full-text search and faceted search, while maintaining the privacy of query data and supporting large query payloads.

Details

Traditionally, search functionalities are implemented using HTTP GET requests where query parameters are appended to the URL. However, when dealing with complex search queries that require sending a lot of data or ensuring the confidentiality of the data, using HTTP POST becomes advantageous. In this pattern, the search parameters are included in the body of the POST request, allowing for larger amounts of data without URL length restrictions and providing additional security measures as the query details are not exposed in the URL.

This pattern is different than the Resource Collection Filtering pattern, as it may allow for more generalized search queries across multiple properties. This pattern may also return results across multiple resource collections, rather than constraining the search to a single resource collection.

For a more simplified search capability, refer to the HTTP Search APIs Using GET page.

Common Pattern Names/Synonyms

  • POST-based Search API
  • Search API with POST
  • HTTP POST Search

Common Use Cases

  1. Secure Searches: When the search query contains sensitive information that should not appear in server logs or browser history.
  2. Complex Queries: For handling large or complex queries, such as those involving multiple search fields, filters, and sorting options.
  3. Full-text Search: When the application needs to perform full-text searches across large datasets or documents.
  4. Faceted Search: Supports advanced search interfaces where users can apply various filters to narrow down search results.

Mermaid Sequence Diagrams

sequenceDiagram
    participant Client
    participant Server
    Client->>Server: POST /search
    Note right of Client: Body contains search parameters as JSON
    Server->>Client: 200 OK
    Note left of Server: JSON response with search results

Examples

API Request Example

Here is an example of an HTTP POST request for a search API where the client is searching for products with specific attributes:

POST /api/search HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "query": "wireless headphones",
    "filters": {
        "brand": ["Sony", "Bose"],
        "price": {"from": 100, "to": 400}
    },
    "sort": "price_asc",
    "page": 1,
    "pageSize": 10
}

API Response Example

This is an example response from the server, providing a list of products that match the search criteria:

{
    "totalResults": 85,
    "results": [
        {
            "id": "12345",
            "name": "Sony Wireless Headphones",
            "price": 299,
            "currency": "USD",
            "available": true
        },
        {
            "id": "12346",
            "name": "Bose Wireless Headphones",
            "price": 349,
            "currency": "USD",
            "available": true
        }
    ],
    "page": 1,
    "totalPages": 9,
    "pageSize": 10
}

Updated: