RESTful API路径设计：资源过滤与属性裁剪最佳实践咨询

Hi there! Let's break down practical, industry-standard approaches for designing your API endpoints based on the scenarios you've outlined, all aligned with core REST principles.

Scenario 1: Return titles of all questions #

Recommended Endpoint #

GET /questions?fields=title

Rationale: #

• This leverages the representation filtering pattern—using a fields query parameter to narrow down the response payload to only the data you need. It keeps your API flexible: you can easily extend it later to include other fields (e.g., ?fields=title,questionId) without creating entirely new endpoints.
• It preserves the base /questions resource, which cleanly maps to the collection of Question entities, staying true to REST's focus on resources over actions.

Scenario 2: Return titles of all TECHNICAL area questions #

Recommended Endpoint #

GET /questions?area=TECHNICAL&fields=title

Rationale: #

• Combine resource filtering (via area=TECHNICAL) with representation filtering (via fields=title). This is a scalable approach—if you later need to filter by difficulty level or state, you just add another query parameter (e.g., ?area=TECHNICAL&difficultyLevel=EASY) instead of building custom endpoints.
• Avoids cluttering your API with overly specific paths like /technical-questions/titles, which would become hard to maintain as new filter criteria emerge.

Scenario 3: Return questions with the ALGORITHM skill #

Recommended Endpoint #

GET /questions?skills=ALGORITHM

Rationale: #

• Using a query parameter for skill filtering keeps your API consistent with the previous patterns. For multi-skill filters, you can extend this to support comma-separated values: ?skills=ALGORITHM,PROGRAMMING.
• If skills were a standalone top-level resource in your API, you could also consider GET /skills/ALGORITHM/questions to emphasize the relationship between skills and questions. But since skills are nested attributes of your Question resource, the first approach is simpler and more intuitive.

Core REST Principles Guiding These Choices #

• Resource-Oriented Design: All endpoints center on the Question resource, avoiding action-based paths (like /get-question-titles) which contradict REST's preference for nouns over verbs.
• Flexibility & Scalability: Query parameters let you mix and match filters and field selections without bloating your API with one-off endpoints, making it easier to adapt to new requirements.
• Consistency: A uniform pattern (base resource + query params for filtering/selection) makes your API predictable for other developers—they won't have to guess custom endpoint names for every possible use case.

内容的提问来源于stack exchange，提问作者ThinkGeek