api-rest-conventions

michaellperry's avatarfrom michaellperry

Essential RESTful API design conventions for URL patterns, HTTP methods, and response formats. For detailed implementations and advanced patterns, see references section.

⭐0stars🔀0forks📁View on GitHub🕐Updated Jan 11, 2026
[API Helpers]

When & Why to Use This Skill

This Claude skill provides a comprehensive framework for designing high-quality RESTful APIs. It outlines essential conventions for resource-based URL patterns, proper HTTP method mapping, and standardized response formats, ensuring that your API architecture is consistent, maintainable, and developer-friendly.

Use Cases

  • Standardizing URL naming conventions and resource hierarchies during the initial design phase of a new web service.
  • Ensuring correct HTTP method usage (GET, POST, PUT, PATCH, DELETE) to maintain idempotency and follow REST architectural constraints.
  • Designing consistent error response structures and status codes to improve debugging and client-side integration.
  • Providing a reference guide for development teams to maintain API consistency across different microservices and modules.
nameapi-rest-conventions
descriptionEssential RESTful API design conventions for URL patterns, HTTP methods, and response formats. For detailed implementations and advanced patterns, see references section.

RESTful API Design Conventions

Essential patterns for designing consistent, maintainable RESTful APIs.

Core Principles

1. Resource-Based URLs

Use plural nouns for resources, avoid actions in URLs.

// ✅ Good
GET    /api/venues          // Get all venues
GET    /api/venues/{id}     // Get specific venue
POST   /api/venues          // Create venue
PUT    /api/venues/{id}     // Update venue
DELETE /api/venues/{id}     // Delete venue

// ❌ Bad
GET    /api/getVenues
POST   /api/createVenue

2. HTTP Method Usage

Map operations to appropriate HTTP methods.

GET    /api/venues        // Read (safe, cacheable)
POST   /api/venues        // Create (not idempotent)
PUT    /api/venues/{id}   // Replace (idempotent)
PATCH  /api/venues/{id}   // Partial update (idempotent)
DELETE /api/venues/{id}   // Remove (idempotent)

3. Nested Resources

Structure related resources hierarchically.

// ✅ Good - Clear hierarchy
GET    /api/venues/{id}/acts         // Acts for venue
POST   /api/venues/{id}/acts         // Create act for venue
GET    /api/acts/{id}/shows          // Shows for act

// ❌ Bad - Flat structure loses context
GET    /api/acts?venueId={id}

Response Formats

Success Responses

Standard patterns for successful operations.

// GET - Return resource(s)
200 OK
{
  "id": 123,
  "name": "Music Hall",
  "capacity": 500
}

// POST - Return created resource with location
201 Created
Location: /api/venues/123
{
  "id": 123,
  "name": "Music Hall"
}

// PUT/PATCH - Return updated resource
200 OK
{
  "id": 123,
  "name": "Updated Music Hall"
}

// DELETE - Confirm deletion
204 No Content

Error Responses

Consistent error structure.

400 Bad Request
{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Invalid venue data",
    "details": [
      {
        "field": "name",
        "message": "Name is required"
      }
    ]
  }
}

Common Status Codes

Essential status codes for RESTful APIs:

  • 200 OK - Successful GET, PUT, PATCH
  • 201 Created - Successful POST
  • 204 No Content - Successful DELETE
  • 400 Bad Request - Invalid client request
  • 401 Unauthorized - Missing/invalid authentication
  • 403 Forbidden - Access denied
  • 404 Not Found - Resource doesn't exist
  • 409 Conflict - Resource conflict (duplicate)
  • 422 Unprocessable Entity - Validation errors
  • 500 Internal Server Error - Server error

References

For detailed implementations and advanced patterns: