The Resource Collection Filtering pattern allows clients to specify constraints to limit the data returned by an API in a response. This pattern is essential for reducing network load, improving user experience, and optimizing server-side resource usage by providing only the relevant subset of data to the client.

Details

In modern web and mobile applications, transmitting large volumes of data over the network can be inefficient and costly. The Resource Collection Filtering pattern addresses this by enabling clients to request only a subset of resources that match specific criteria. Effective use of this pattern can significantly enhance the performance and scalability of API-driven applications.

This pattern is typically implemented via GET query parameters that the API processes to return filtered results.

Common Pattern Names/Synonyms

  • Query Filtering
  • Subset Retrieval
  • Narrowing Down Resources

Common Use Cases

  1. E-commerce Platforms: Customers can filter products by price, category, brand, or rating.
  2. Social Media Apps: Users can filter posts or news feeds based on tags, author, or date.
  3. Content Management Systems: Admins can filter articles, images, or videos by status, creator, or publish date.
  4. Customer Relationship Management (CRM) Systems: Sales reps can filter contacts, leads, or opportunities by region, status, or last contact date.

Mermaid Sequence Diagrams

sequenceDiagram
    participant C as Client
    participant S as Server
    C->>+S: GET /resources?filter=type:public,date>2022
    S->>-C: Response with filtered resources

Examples

Example 1: Basic Filtering

A client requests a list of public events created after the year 2022.

Request:

GET /events?visibility=public&createdAfter=2022 HTTP/1.1
Host: api.example.com

Response:

{
  "events": [
    {
      "id": "123",
      "name": "Open API Conference",
      "date": "2023-07-10"
    },
    {
      "id": "456",
      "name": "Tech Innovators Meetup",
      "date": "2024-05-16"
    }
  ]
}

Example 2: Complex Filtering

A client requests a list of products in the ‘electronics’ category that are priced between $50 and $500 and are rated 4 stars or higher.

Request:

GET /products?category=electronics&price[gte]=50&price[lte]=500&rating[gte]=4 HTTP/1.1
Host: api.example.com

Response:

{
  "products": [
    {
      "id": "789",
      "name": "Smartphone High-end",
      "price": 499,
      "rating": 4.5
    },
    {
      "id": "1011",
      "name": "Compact Camera Pro",
      "price": 450,
      "rating": 4.2
    }
  ]
}

Updated: