REST API URL Design: kebab vs snake_case
What's the best case format for REST API URLs? Explore industry standards, framework conventions, and practical examples for designing clean APIs.
REST API URL design is critical for developer experience. Your URL structure should be intuitive, consistent, and easy to remember. One of the first decisions is choosing the right case format.
The URL Case Format Debate
kebab-case (Recommended)
Used by: Google, GitHub, Stripe, Shopify, most major APIs
GET /api/user-profiles/:id
POST /api/order-items
GET /api/payment-methodsPros:
- Most readable format for URLs
- Works well in all browsers without encoding
- Matches domain name conventions
- Industry standard for REST APIs
snake_case
Used by: Some Python-based APIs, Reddit API
GET /api/user_profiles/:id
POST /api/order_items
GET /api/payment_methodsPros:
- Matches Python naming conventions
- Consistent with database column names if using snake_case
Cons:
- Underscores can be hard to see when underlined in links
- Less common than kebab-case for URLs
camelCase (Not Recommended for URLs)
Why not: URLs are case-insensitive by convention, and camelCase creates ambiguity
GET /api/userProfiles/:id ❌
GET /api/orderItems ❌Complete REST API URL Best Practices
1. Use Nouns, Not Verbs
✅ GET /api/users
✅ POST /api/users
❌ GET /api/get-users
❌ POST /api/create-user2. Use Plural Nouns
✅ GET /api/users
✅ GET /api/users/:id
❌ GET /api/user
❌ GET /api/user/:id3. Use Hierarchical Structure for Relationships
GET /api/users/:userId/orders
GET /api/users/:userId/orders/:orderId
GET /api/posts/:postId/comments4. Use Query Parameters for Filtering
GET /api/users?role=admin&status=active
GET /api/products?category=electronics&price[lt]=100
GET /api/posts?sort=-created_at&limit=105. Version Your API
GET /api/v1/users
GET /api/v2/users
OR
GET /api/users (with header: Accept: application/vnd.api.v1+json)6. Use Standard HTTP Methods
GET- Retrieve resourcesPOST- Create resourcesPUT- Update/replace resourcesPATCH- Partially update resourcesDELETE- Delete resources
7. Return Proper Status Codes
- 200 - OK
- 201 - Created
- 204 - No Content
- 400 - Bad Request
- 401 - Unauthorized
- 404 - Not Found
- 500 - Internal Server Error
Real-World Examples
GitHub API (kebab-case)
GET https://api.github.com/repos/:owner/:repo/pull-requests
GET https://api.github.com/users/:username/followingStripe API (kebab-case)
POST https://api.stripe.com/v1/payment-intents
GET https://api.stripe.com/v1/customers/:id/payment-methodsShopify API (kebab-case)
GET https://shop.myshopify.com/admin/api/2024-01/products.json
POST https://shop.myshopify.com/admin/api/2024-01/custom-collections.jsonDocumentation Tips
- Clearly state your naming convention in API documentation
- Provide examples for every endpoint
- Include request/response samples
- Document all query parameters and filters
- Show error response examples
Recommendation: Use kebab-case for REST API URLs unless you have a very strong reason not to. It's the industry standard, most readable, and what developers expect.
Try Text-Case.com Today
Transform text with 41 professional tools. Free, fast, and no signup required.
Start Converting