API Design & REST/gRPC

from flask import Flask, jsonify, request, abort

app = Flask(__name__)

# In-memory store for demonstration
users = {}
next_id = 1


@app.route('/api/v1/users', methods=['GET'])
def list_users():
    """List all users with pagination."""
    page = request.args.get('page', 1, type=int)
    per_page = request.args.get('per_page', 20, type=int)

    all_users = list(users.values())
    start = (page - 1) * per_page
    end = start + per_page

    return jsonify({
        'data': all_users[start:end],
        'meta': {
            'page': page,
            'per_page': per_page,
            'total': len(all_users)
        }
    }), 200


@app.route('/api/v1/users', methods=['POST'])
def create_user():
    """Create a new user."""
    global next_id
    data = request.get_json()

    if not data or 'name' not in data:
        abort(400, description='Name is required')

    user = {
        'id': next_id,
        'name': data['name'],
        'email': data.get('email', '')
    }
    users[next_id] = user
    next_id += 1

    return jsonify({'data': user}), 201


@app.route('/api/v1/users/<int:user_id>', methods=['GET'])
def get_user(user_id):
    """Retrieve a single user by ID."""
    user = users.get(user_id)
    if not user:
        abort(404, description='User not found')
    return jsonify({'data': user}), 200


@app.route('/api/v1/users/<int:user_id>', methods=['PUT'])
def update_user(user_id):
    """Update an existing user."""
    if user_id not in users:
        abort(404, description='User not found')

    data = request.get_json()
    users[user_id].update({
        'name': data.get('name', users[user_id]['name']),
        'email': data.get('email', users[user_id]['email'])
    })
    return jsonify({'data': users[user_id]}), 200


@app.route('/api/v1/users/<int:user_id>', methods=['DELETE'])
def delete_user(user_id):
    """Delete a user."""
    if user_id not in users:
        abort(404, description='User not found')
    del users[user_id]
    return '', 204

syntax = "proto3";

package userservice;

// The User service definition
service UserService {
    // Retrieve a single user
    rpc GetUser (GetUserRequest) returns (User);

    // List users with pagination
    rpc ListUsers (ListUsersRequest) returns (ListUsersResponse);

    // Create a new user
    rpc CreateUser (CreateUserRequest) returns (User);

    // Stream user activity events
    rpc StreamActivity (ActivityRequest) returns (stream ActivityEvent);
}

message GetUserRequest {
    int32 id = 1;
}

message User {
    int32 id = 1;
    string name = 2;
    string email = 3;
    int64 created_at = 4;
}

message ListUsersRequest {
    int32 page = 1;
    int32 per_page = 2;
}

message ListUsersResponse {
    repeated User users = 1;
    int32 total = 2;
}

message CreateUserRequest {
    string name = 1;
    string email = 2;
}

message ActivityRequest {
    int32 user_id = 1;
}

message ActivityEvent {
    string event_type = 1;
    string description = 2;
    int64 timestamp = 3;
}