[ADP-307] Inspiring URI Design Collection

This document collects inspiring URI design patterns observed from various public API documentation. While these design patterns may extend beyond traditional RESTful API path design conventions, their semantic clarity often reduces the need for additional Header or Request design requirements.

Note: These design patterns are for reference only and may not be suitable for all API design scenarios.

URI Design Pattern Categories

1. Modifier Pattern

Using modifiers at the end of paths to express specific states or scopes of resources:

GET /users/{username}/events/public      # Get public events
GET /user/marketplace_purchases/stubbed   # Get test purchase information
POST /applications/{client_id}/token/scoped  # Create a token with specific scope

2. Identifier Design Pattern

Using semantic identifiers to improve URL readability:

GET /apps/{app_slug}  # Using readable slug instead of UUID

3. Resource Relationship Expression Pattern

Clearly expressing relationships and operations between resources:

GET /enterprises/{enterprise}/actions/permissions/selected-actions
GET /user/starred/{owner}/{repo}  # Check if authenticated user starred the repository
GET /orgs/{org}/installations    # Get organization installations

4. Specific Operation Pattern

Specialized operations for specific resources:

POST /repos/{owner}/{repo}/merge-upstream  # Merge upstream changes
POST /repos/{owner}/{repo}/branches/{branch}/protection/enforce_admins  # Enforce admin protection

5. Resource Status Query Pattern

For querying specific resource states or associated data:

GET /users/self/requested-by     # Instagram: Query users requesting to follow
GET /user/starred               # Get starred items
GET /v3/groups/owned           # GitLab: Get user-owned groups

6. Singleton Resource Pattern

For representing resources that have only one instance within a specific context:

GET /user/profile              # Get current user's profile
GET /system/configuration      # Get system configuration
GET /apis/{api-id}/stages/dev  # Get development stage of a specific API

Welcome to contribute more API design examples to enrich this collection.

Changelog

• 2025.03.07: Fully rewrite this document