Developer Experience (DX) Best Practices: Building Great Developer APIs and Tools

dx_principles = {
    "developer_first": {
        "description": "Design for developer needs, not internal convenience",
        "questions": [
            "What's the simplest way to do X?",
            "What does the developer need to know?",
            "What would make this delightful?"
        ]
    },
    
    "convention_over_configuration": {
        "description": "Provide sensible defaults, allow overrides",
        "example": "Most users don't need to configure anything"
    },
    
    "progressive_disclosure": {
        "description": "Simple for beginners, powerful for experts",
        "example": "QuickStart vs advanced features"
    },
    
    "clear_feedback": {
        "description": "Tell developers what happened and why",
        "example": "Error messages should explain the fix"
    },
    
    "be_consistent": {
        "description": "Same patterns across all surfaces",
        "example": "Method naming, error handling"
    }
}

# Good REST API design

naming:
  - Use nouns for resources: /users, /orders
  - Use plural: /users not /user
  - Use kebab-case: /user-profiles
  - Nest relationships: /users/123/orders

responses:
  - Use standard HTTP status codes
  - Always return consistent envelope
  - Include helpful metadata
  
status_codes:
  "200": "Success"
  "201": "Created"
  "204": "No Content"
  "400": "Bad Request"
  "401": "Unauthorized"
  "403": "Forbidden"
  "404": "Not Found"
  "429": "Too Many Requests"
  "500": "Internal Error"

// Good response format
{
  "data": {
    "id": "123",
    "type": "user",
    "attributes": {
      "name": "John Doe",
      "email": "[email protected]"
    }
  },
  "meta": {
    "request_id": "abc-123"
  },
  "links": {
    "self": "/users/123",
    "orders": "/users/123/orders"
  }
}

# Good GraphQL schema design

type User {
  id: ID!
  name: String!
  email: String!
  
  # Clear naming, avoid generic names
  orders: OrderConnection!
  
  # Relay cursor connections for pagination
  ordersAfter(after: String, first: Int): OrderConnection
}

# Input types for mutations
input CreateUserInput {
  name: String!
  email: String!
  age: Int
}

# Clear mutation naming
type Mutation {
  createUser(input: CreateUserInput!): CreateUserPayload!
  updateUser(id: ID!, input: UpdateUserInput!): UpdateUserPayload!
}

# Good error handling
type MutationResult {
  success: Boolean!
  errors: [UserError!]!
  user: User
}

type UserError {
  field: String!
  message: String!
}

# Good SDK design

sdk_principles = {
    "installable": {
        "description": "Easy to install with package manager",
        "example": "pip install stripe, npm install stripe"
    },
    
    "configurable": {
        "description": "Sensible defaults with override options",
        "example": "stripe = Stripe(key), stripe = Stripe(key, timeout=30)"
    },
    
    "typed": {
        "description": "Type hints for IDE support",
        "example": "def create_user(name: str) -> User:"
    },
    
    "documented": {
        "description": "Docstrings for every method",
        "example": "def create_user(name: str) -> User:\n    '''Create a new user'''"
    },
    
    "testable": {
        "description": "Mockable, good test coverage",
        "example": "Use interfaces for external services"
    }
}

# Good SDK implementation

from typing import Optional, List
from dataclasses import dataclass
import requests

@dataclass
class User:
    id: str
    name: str
    email: str
    
    @classmethod
    def from_dict(cls, data: dict) -> 'User':
        return cls(**data)

class UserClient:
    """Client for managing users."""
    
    def __init__(
        self,
        api_key: str,
        base_url: str = "https://api.example.com",
        timeout: int = 30
    ):
        self.api_key = api_key
        self.base_url = base_url
        self.timeout = timeout
        self._session = requests.Session()
        self._session.headers.update({
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json"
        })
    
    def get_user(self, user_id: str) -> User:
        """Get a user by ID.
        
        Args:
            user_id: The user ID
            
        Returns:
            User object
            
        Raises:
            NotFoundError: If user not found
            APIError: For other API errors
        """
        response = self._session.get(
            f"{self.base_url}/users/{user_id}",
            timeout=self.timeout
        )
        
        if response.status_code == 404:
            raise NotFoundError(f"User {user_id} not found")
        response.raise_for_status()
        
        return User.from_dict(response.json()["data"])
    
    def list_users(self, limit: int = 20) -> List[User]:
        """List all users.
        
        Args:
            limit: Maximum number of users to return (default 20)
            
        Returns:
            List of User objects
        """
        response = self._session.get(
            f"{self.base_url}/users",
            params={"limit": limit},
            timeout=self.timeout
        )
        response.raise_for_status()
        
        return [User.from_dict(u) for u in response.json()["data"]]

# BAD errors
raise Exception("Error")
raise ValueError("Invalid")

# GOOD errors

class APIError(Exception):
    """Base exception for API errors."""
    def __init__(self, message: str, code: str, status: int):
        self.message = message
        self.code = code
        self.status = status
        super().__init__(message)

class ValidationError(APIError):
    """Raised when input validation fails."""
    def __init__(self, field: str, message: str):
        super().__init__(
            f"Validation failed for {field}: {message}",
            code="VALIDATION_ERROR",
            status=400
        )
        self.field = field

class NotFoundError(APIError):
    """Raised when a resource is not found."""
    def __init__(self, resource: str, id: str):
        super().__init__(
            f"{resource} with id {id} not found",
            code="NOT_FOUND",
            status=404
        )

# Usage with helpful messages
def get_user(user_id: str) -> User:
    if not user_id:
        raise ValidationError("user_id", "cannot be empty")
    
    if not user_id.startswith("usr_"):
        raise ValidationError(
            "user_id",
            "must start with 'usr_'"
        )
    
    # ... fetch user

# Essential documentation sections

documentation = {
    "getting_started": {
        "description": "Quick 5-minute intro",
        "content": [
            "Installation",
            "Authentication",
            "First API call"
        ]
    },
    
    "concepts": {
        "description": "Key concepts explained",
        "content": [
            "How the API works",
            "Authentication flows",
            "Webhooks"
        ]
    },
    
    "api_reference": {
        "description": "Complete API reference",
        "content": [
            "All endpoints",
            "Parameters",
            "Response schemas"
        ]
    },
    
    "guides": {
        "description": "Task-oriented tutorials",
        "content": [
            "How to create a user",
            "How to handle webhooks",
            "Error handling"
        ]
    },
    
    "troubleshooting": {
        "description": "Common issues",
        "content": [
            "Error codes explained",
            "Debugging tips",
            "FAQ"
        ]
    },
    
    "code_samples": {
        "description": "Copy-paste examples",
        "content": [
            "cURL",
            "Python",
            "JavaScript",
            "Go"
        ]
    }
}

# OpenAPI/Swagger

openapi: 3.0.0
info:
  title: My API
  version: 1.0.0

paths:
  /users:
    get:
      summary: List users
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Users'

# Use Swagger UI or Redoc for interactive docs

dx_metrics = {
    "time_to_first_call": {
        "description": "Time to make first successful API call",
        "target": "< 5 minutes"
    },
    
    "documentation_completion": {
        "description": "Time to complete common tasks",
        "target": "Clear for basic tasks"
    },
    
    "error_clarity": {
        "description": "Can developers fix errors without support?",
        "target": "> 80% self-solved"
    },
    
    "sdk_adoption": {
        "description": "Are developers using your SDK vs raw API?",
        "target": "> 70%"
    },
    
    "nps": {
        "description": "Developer Net Promoter Score",
        "target": "> 50"
    }
}

# How to collect feedback

feedback_channels:
  - name: "GitHub issues"
    use: "Bug reports, feature requests"
    
  - name: "Discord/Slack community"
    use: "Real-time help, discussions"
    
  - name: "Developer surveys"
    use: "Quarterly satisfaction"
    
  - name: "Usage analytics"
    use: "Feature usage, drop-off points"
    
  - name: "Support tickets"
    use: "Pain point identification"