API design & gRPC
REST best practices, protobuf, API versioning, and backward-compatible service contracts.
Convert Protobuf to JSON and Dict in Python
Provides static helper methods to convert between protobuf messages, JSON strings, and Python dictionaries using the google.protobuf library.
from google.protobuf.json_format import MessageToJson, Parse
import json
class DataConverter:
"""Helper class to convert between protobuf messages and common formats."""
@staticmethod
def to_json(message, indent=2):
"""Convert a protobuf message to JSON string."""
return MessageToJson(me…Create a Data Helper in Python for gRPC-style APIs
This code builds a simple DataHelper class that mimics gRPC request/response handling with in-memory storage, JSON serialization, and basic CRUD operations for beginners.
import json
from dataclasses import dataclass, asdict
from typing import Dict, Any
@dataclass
class User:
user_id: int
name: str
email: str
class DataHelper:
"""Simple helper to demonstrate gRPC-like data handling for beginners."""
def __init__(self) -> None:
self._users: Dict[int, Use…Format data in Python using dataclasses like gRPC messages
Convert Python dataclasses to and from dicts and format them gRPC-style for clean data handling.
from dataclasses import dataclass
from typing import Any, Dict, List, Optional
@dataclass
class ProductInfo:
"""Data class representing a gRPC-style product message."""
name: str
price: float
tags: List[str]
description: Optional[str] = None
def to_dict(self) -> Dict[str, Any]:
"""C…Generate an OpenAPI Spec from Mock Routes in Python
This Python script generates an OpenAPI 3.0 specification from a simple mock routes dictionary, mapping each HTTP method to response examples.
import json
from pathlib import Path
def generate_openapi_spec(routes: dict, title: str = "Mock API", version: str = "1.0.0") -> dict:
paths = {}
for route, methods in routes.items():
path_item = {}
for method, response_data in methods.items():
method = method.lower()
…How to Add HATEOAS Links to a Python API Response
Build a Python API resource class that adds self and next HATEOAS links to JSON responses, with a mock example for pagination.
import json
class Resource:
def __init__(self, name, data, next_page=None):
self.links = {"self": f"/api/resources/{name}"}
if next_page is not None:
self.links["next"] = f"/api/resources?page={next_page}"
self.data = data
def to_dict(self):
return {"links": self.…How to Add a Correlation ID Tracing Header in Python
A mock middleware generates or preserves a correlation ID header and logs structured JSON messages with it for API request tracing.
import uuid
import json
from dataclasses import dataclass, field
from typing import Optional
@dataclass
class Request:
headers: dict = field(default_factory=dict)
def get(self, key, default=None):
return self.headers.get(key, default)
class CorrelationIdMiddleware:
def __init__(self, header_name…How to Build Cursor Pagination with Next and Prev Tokens in Python
A minimal cursor pagination implementation that returns next and previous cursor tokens for navigating a dataset.
from pprint import pprint
def make_cursor(page):
return f"page:{page:04d}"
def parse_cursor(cursor):
_, page = cursor.split(":", 1)
return int(page)
def paginate(all_items, page_size, cursor=None):
start = parse_cursor(cursor) if cursor else 0
end = start + page_size
items = all_items[sta…How to Build a Batch Operations Multi-Status 207 Mock Server in Python
Build a mock HTTP server that accepts a batch of operations and returns HTTP 207 Multi-Status with per-operation status codes in JSON.
from http.server import BaseHTTPRequestHandler, HTTPServer
import json
class BatchHandler(BaseHTTPRequestHandler):
def do_POST(self):
if self.path != "/batch":
self.send_response(404)
self.end_headers()
return
content_length = int(self.headers.get("Content-Leng…How to Build a Data Helper Class in Python for Beginners
Create a beginner-friendly DataHelper class that stores, retrieves, filters, and summarizes records in a list of dictionaries.
from __future__ import annotations
import json
from dataclasses import dataclass, field
from typing import Any, Dict, List, Optional
@dataclass
class DataHelper:
"""A beginner-friendly helper for common data tasks."""
data: List[Dict[str, Any]] = field(default_factory=list)
def add_record(self, record…How to Build a Hypermedia Collection Resource in Python
Creates a paginated hypermedia collection resource with HATEOAS links and embedded items.
import json
import math
class HypermediaCollection:
"""A mock hypermedia collection resource."""
def __init__(self, items, base_url="/api/items"):
self.items = items
self.base_url = base_url
def to_dict(self, page=1, per_page=3):
total = len(self.items)
pages = math.ceil…How to Build a Mock REST GET Endpoint Handler in Python
Create a lightweight mock REST GET server in Python using the standard library, with a dict-based route registry that maps paths to handler functions and returns JSON responses with proper HTTP status codes.
from http.server import BaseHTTPRequestHandler, HTTPServer
import json
# Mock API handler registry
def handle_users():
return {"status": "ok", "data": [{"id": 1, "name": "Alice"}, {"id": 2, "name": "Bob"}]}
def handle_products():
return {"status": "ok", "data": [{"id": 101, "name": "Laptop", "price": 999.99}…How to Build a Simple Data Helper in Python for API Design
Create a beginner-friendly DataHelper class that demonstrates basic CRUD operations (add, get, list, remove) using an in-memory dictionary, ideal for learning API design concepts.
class DataHelper:
"""Simple data helper for beginners learning API design concepts."""
def __init__(self):
self._data = {}
def add_record(self, key, value):
"""Add a record to the store."""
self._data[key] = value
return f"Added: {key} -> {value}"
def get_…How to Build a Simple Filter Helper in Python for API Design
Create a reusable data filter service with dataclasses that mimics gRPC request/response patterns for filtering dataset records.
from dataclasses import dataclass, field
from typing import List, Optional, Dict, Any
@dataclass
class FilterRequest:
"""A simple filter request mirroring a gRPC message structure."""
field_name: str
operator: str # eq, ne, gt, lt, contains
value: Any
page_size: int = 10
page_token: Optional…How to Build a WebSocket Echo Server in Python with asyncio
Create a simple WebSocket echo server using the websockets library and asyncio to handle concurrent connections.
import asyncio
import websockets
async def echo(websocket):
async for message in websocket:
await websocket.send(f"Echo: {message}")
async def main():
async with websockets.serve(echo, "localhost", 8765):
print("WebSocket server started on ws://localhost:8765")
await asyncio.Future() …How to Create an RFC 7807 Error JSON in Python
Construct a structured error response using the RFC 7807 Problem Details format with a reusable function.
import json
from typing import Dict
def create_rfc7807_error(
type_: str,
title: str,
status: int,
detail: str,
instance: str,
extra_fields: Dict[str, object] | None = None,
) -> str:
"""
Build a JSON string following RFC 7807 Problem Details format.
"""
problem = {
"t…How to Decode Basic Auth Credentials in Python
Decode username and password from a Basic Auth header string using base64 and standard string operations.
import base64
def decode_basic_auth(header_value):
"""
Decode credentials from a Basic Auth header value.
Expected format: "Basic base64encoded(username:password)"
Returns a tuple (username, password).
"""
if not header_value.startswith("Basic "):
raise ValueError("Invalid Basic A…How to Implement Content Negotiation with JSON and XML in Python
Build an HTTP server that returns JSON or XML responses based on the client's Accept header, with a 406 response for unsupported formats.
import json
import xml.etree.ElementTree as ET
from http.server import BaseHTTPRequestHandler, HTTPServer
class RequestHandler(BaseHTTPRequestHandler):
def do_GET(self):
data = {"message": "Hello, world!"}
accept_header = self.headers.get("Accept", "")
if "application/json" in accept_hea…How to Implement Pagination with Offset and Limit in Python
A mock API pagination pattern that parses page and per_page query parameters, computes offset and limit, and slices a list of items for a specific page.
def paginate(items, page, per_page):
offset = (page - 1) * per_page
return items[offset:offset + per_page]
def parse_query_params(query_string):
params = {}
if query_string:
for pair in query_string.split("&"):
key, value = pair.split("=")
params[key] = value
page …How to Implement RBAC Permission Checks with a Route Decorator in Python
Build a reusable Python decorator that checks a user's role against allowed roles and raises a custom PermissionError when access is denied.
from functools import wraps
from enum import Enum
class Role(Enum):
ADMIN = "admin"
MODERATOR = "moderator"
USER = "user"
class PermissionError(Exception):
pass
def require_role(*allowed_roles):
def decorator(func):
@wraps(func)
def wrapper(user_role, *args, **kwargs):
…How to Implement Sparse Fieldsets in Python
A function that filters API responses by resource type, returning only requested fields plus IDs, as a sparse fieldset mock.
from dataclasses import dataclass, field
from typing import Dict, List, Optional
@dataclass
class MockResponse:
data: Dict[str, object] = field(default_factory=dict)
included: List[Dict[str, object]] = field(default_factory=list)
def select_fields(
data: Dict[str, object],
sparse_fields: Optional[D…How to Implement a PATCH Partial Update Merge Dict in Python
Implements a recursive merge function that applies HTTP PATCH-like partial updates to a nested dictionary while preserving untouched fields.
import json
def patch_merge(target: dict, patch: dict) -> dict:
"""Simulate HTTP PATCH semantic: shallow-merge patch into a copy of target."""
merged = target.copy()
for key, value in patch.items():
if isinstance(value, dict) and isinstance(merged.get(key), dict):
merged[key] = patch_m…How to Mock Content-Disposition and Extract Filename in Python
Parse and mock Content-Disposition headers in Python to extract filenames, handling both plain and RFC 5987 encoded values.
import os
from pathlib import Path
import re
from unittest.mock import patch
def get_filename_from_content_disposition(header_value):
"""
Extract filename from a Content-Disposition header value.
Supports both filename and filename* parameters (RFC 5987).
"""
if not header_value:
return No…How to Mock HTTP 304 Responses with If-None-Match in Python
Spin up a local HTTP server that returns a 304 Not Modified when a request carries a matching ETag, useful for testing cache behavior.
from http.server import BaseHTTPRequestHandler, HTTPServer
from threading import Thread
import urllib.request
ETAG = '"abc123"'
BODY = b'{"status": "ok"}'
class MockServer(BaseHTTPRequestHandler):
def do_GET(self):
if self.headers.get('If-None-Match') == ETAG:
self.send_response(304)
…How to Mock OAuth2 Bearer Token Auth Middleware in Python
Create a simple OAuth2 bearer token authentication middleware that verifies signed tokens and enforces scope-based access control.
import hmac
import time
import base64
import json
from functools import wraps
VALID_TOKENS = {"test_token_123": {"user": "alice", "scope": "read:posts"}}
def generate_token(username: str) -> str:
payload = {"user": username, "iat": int(time.time())}
encoded = base64.urlsafe_b64encode(json.dumps(payload).enc…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.