API design & gRPC
REST best practices, protobuf, API versioning, and backward-compatible service contracts.
How to Poll an Operation Status Endpoint in Python
Mock a polling endpoint in Python that simulates checking an async operation's status until it completes or times out.
import time
import random
def poll_status(url: str, timeout: float = 5.0) -> dict:
"""Mock a polling endpoint that eventually returns a completed status."""
start = time.time()
while time.time() - start < timeout:
# Simulate delayed response
time.sleep(0.2)
# 80% chance to report …How to Prefix Python API URIs with a Version Slug
Build a versioned API endpoint by optionally adding a version prefix like v1 to the URL path using the stdlib urllib module.
from urllib.parse import urlparse
BASE_URL = "https://api.example.com"
def build_uri(resource, version="v1"):
"""Mock a versioned API URI with an optional v1 prefix."""
parsed = urlparse(BASE_URL)
prefix = f"/{version}" if version else ""
return f"{parsed.scheme}://{parsed.netloc}{prefix}/{resource.l…How to Propagate X-Request-ID in Python
Generate a unique request ID when one is missing and pass it through API calls for distributed tracing.
import uuid
def generate_request_id() -> str:
"""Generate a unique request ID similar to X-Request-ID header."""
return str(uuid.uuid4())
def propagate_request_id(request_id: str | None) -> str:
"""Return the request ID for propagation, generating one if missing."""
if request_id:
return re…How to Serialize a Dataclass to JSON in Python
Serialize a Python dataclass instance to JSON using asdict and json.dumps for API responses or mocks.
from dataclasses import dataclass, asdict
import json
@dataclass
class UserResponse:
id: int
name: str
email: str
active: bool = True
if __name__ == "__main__":
response = UserResponse(id=42, name="Ada Lovelace", email="ada@example.com")
print(json.dumps(asdict(response), indent=2))How to Validate Data in Python for Beginners
A beginner-friendly Python class for validating required fields, types, ranges, and allowed choices in dict payloads.
import json
from typing import Any, Dict, List, Optional, Union
class Validator:
"""A simple validate data helper designed for beginners."""
def __init__(self, data: Union[Dict[str, Any], List[Any]]):
self.data = data
self.errors: Dict[str, str] = {}
def validate_required(self, field: s…How to Validate JWT Claims (exp, iss, aud) in Python
This code demonstrates how to decode and validate a JWT's essential claims—expiration (exp), issuer (iss), and audience (aud)—using the PyJWT library, returning clear error messages for common validation failures.
import jwt
from datetime import datetime, timezone, timedelta
SECRET = "mock-secret"
def validate_token(token, expected_iss, expected_aud):
try:
decoded = jwt.decode(
token,
SECRET,
algorithms=["HS256"],
options={"require": ["exp", "iss", "aud"]},
…How to Validate a JWT Signature in Python with a Mock Secret
Validates a JWT's signature using a mock secret, decoding and handling expired or invalid tokens gracefully.
import jwt
import time
SECRET = "mock_secret_key_123"
def validate_token(token):
try:
payload = jwt.decode(token, SECRET, algorithms=["HS256"])
return f"Valid token. Payload: {payload}"
except jwt.ExpiredSignatureError:
return "Token expired"
except jwt.InvalidTokenError:
…How to handle CORS preflight OPTIONS requests in Python
Create a mock HTTP server with a CORS preflight OPTIONS handler that returns the correct headers for browser-based API requests.
from http.server import BaseHTTPRequestHandler, HTTPServer
class CORSRequestHandler(BaseHTTPRequestHandler):
def _send_cors_headers(self):
self.send_header("Access-Control-Allow-Origin", "*")
self.send_header("Access-Control-Allow-Methods", "GET, POST, PUT, DELETE, OPTIONS")
self.send_head…How to mock a REST POST endpoint in Python
Create a simple mock REST server that responds to POST requests with a 201 status and a JSON body.
import json
from http.server import BaseHTTPRequestHandler, HTTPServer
class MockHandler(BaseHTTPRequestHandler):
def do_POST(self):
content_length = int(self.headers.get("Content-Length", 0))
body = self.rfile.read(content_length) if content_length else b"{}"
try:
data = json…Return Proper HTTP Status Codes Table in Python
Mock HTTP status code table with proper numeric and textual representations, including formatted status lines and a filtered table view.
# Mock HTTP status code table with proper numeric and textual representations
codes = {
200: "OK",
201: "Created",
204: "No Content",
301: "Moved Permanently",
302: "Found",
304: "Not Modified",
400: "Bad Request",
401: "Unauthorized",
403: "Forbidden",
404: "Not Found",
50…Scope-based authorization in Python
A simple Python class that checks user scopes against required permissions for a resource, returning an authorization decision.
class ScopeAuthorization:
def __init__(self):
self.scopes = {
"read": ["resource:read"],
"write": ["resource:read", "resource:write"],
"admin": ["resource:read", "resource:write", "resource:delete"]
}
def authorize(self, user_scopes, required_scope, resource…Serve Swagger UI with Python's built-in HTTP server
Hosts a self-contained Swagger UI with a mock OpenAPI spec using only Python's standard library HTTP server.
from http.server import HTTPServer, SimpleHTTPRequestHandler
import os
import tempfile
SWAGGER_HTML = """<!DOCTYPE html>
<html>
<head>
<title>Mock Swagger UI</title>
<link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@4/swagger-ui.css">
</head>
<body>
<div id="swagger-ui"></div>
<script src…Sort Python list by query param order_by
Sort a list of dataclass objects dynamically by a field name passed as a query param, with asc/desc direction support.
from dataclasses import dataclass
@dataclass
class Item:
name: str
price: int
def sort_items(items, order_by, direction="asc"):
if order_by not in ("name", "price"):
raise ValueError(f"Unsupported sort field: {order_by}")
reverse = direction.lower() == "desc"
return sorted(items, key=l…Browse by section
Each section groups closely related Python snippets.
API design & gRPC — Python code examples
What you will find here
This page collects api design & grpc snippets — short, copy-ready Python you can paste into our free online IDE and run without installing anything. Each sample includes a plain-English explanation and the full source code.
Samples vs tutorials and challenges
Samples are quick reference — one concept per page. For step-by-step teaching, use our Python tutorials. To test yourself, try quizzes or coding challenges. Clean up style with the Python formatter.