[ RFC ] API Endpoint Design for Filtering a specific Document by specific fields

Abstract

This RFC aims to discuss the appropriate API endpoint design for filtering progresses based on user and date parameters in a RESTful API. The goal is to determine the most suitable approach for providing filtering capabilities while adhering to RESTful principles and maintaining API consistency.

When implementing an API endpoint to retrieve a specific document from the collection based on the specific user and a specified date criteria, For a particular user and a particular date we will have a unique document.

two common approaches are often considered:

Using Path Parameters:

/progresses/user/XGqmn2yJoneT1aXXh22P/date/2023-05-21

Using Query Parameters:

/progresses?userId=XGqmn2yJoneT1aXXh22P&date=2023-05-21

This RFC aims to discuss the advantages and considerations of each approach to determine the most RESTful and effective solution.

Path Parameters
Using path parameters in the API endpoint structure can provide a more hierarchical and resource-oriented design. It is commonly used when the values are considered mandatory and represent essential parts of the resource identification. However, it's important to note that path parameters are not typically used for filtering data, but rather for specifying specific resource identifiers.

Query Parameters
Using query parameters offers a more flexible and concise approach to provide filtering capabilities. Query parameters are commonly used when the values are optional and used for filtering and pagination. Query parameters allow for a clear separation between the base endpoint and the filtering parameters, making the API more intuitive for API consumers.

We kindly request that you review the attached API design proposal and share your comments, suggestions, and concerns . Your feedback will enable us to refine the API design and ensure its effectiveness and usability.