Junchuan Zhang | Jacky (He/His)

Junchuan Zhang | Jacky (He/His)

Python Rest from OAS Simulator (PyROS)

This project is publicly accessible. Click to access.

Published:

5 minute read

Project Overview

PyROS (Python Rest from OAS Simulator) is a generic REST server simulator that dynamically generates mock HTTP endpoints from OpenAPI Specification (OAS) files. Developed during the JLR Hackathon 5.0, the system enables efficient API testing and development without requiring actual backend services.

Core Value & Significance

In software development and testing, developers often need to test frontend applications or integrations before backend services are ready. PyROS addresses this challenge by:

  • Dynamic Endpoint Generation: Automatically creates mock endpoints from OAS files without code changes
  • Custom Response Configuration: Configure custom HTTP status codes and JSON responses for any endpoint at runtime
  • No Backend Required: Test frontend applications and integrations without waiting for backend development
  • Easy Integration: Works seamlessly with existing testing frameworks and tools like Postman
  • GUI Management: Visual interface for endpoint management and response configuration

The system is particularly valuable for frontend developers, QA engineers, and integration teams who need to test against API specifications before actual services are available.

Technical Stack

Backend

  • Framework: FastAPI with Uvicorn ASGI server
  • Runtime: Python 3
  • API Specification: OpenAPI 3.0.0 (OAS) YAML file parsing
  • Libraries: PyYAML for YAML parsing, Requests for HTTP communication

GUI Application

  • Framework: Tkinter for desktop application interface
  • Features: Visual endpoint management, custom response configuration, YAML file processing

Deployment

  • Containerization: Docker with Ubuntu 22.04 base image
  • X11 Forwarding: GUI support through X11 forwarding for remote desktop access
  • Port: Default server port 6767

Key Features

1. Dynamic Endpoint Generation

  • OAS File Processing: Automatically parse OpenAPI Specification files and generate mock endpoints
  • URL Template Matching: Support for path parameters with enum validation
  • Enum Expansion: Automatic generation of concrete URLs from enum definitions
  • Method Support: Full HTTP method support (GET, POST, PUT, DELETE)

2. Custom Response Configuration

  • Runtime Configuration: Modify endpoint responses without server restart
  • Custom HTTP Codes: Set specific HTTP status codes for any endpoint
  • Custom JSON Bodies: Configure custom JSON response bodies
  • Per-Method Configuration: Different responses for different HTTP methods on the same endpoint

3. GUI Management Interface

  • Connection Management: Connect to PyROS server with configurable URL
  • YAML Configuration: Load and process OAS specification files through file browser
  • Endpoint Management: Visual interface for viewing and managing registered endpoints
  • Custom Response Editor: Interactive dialog for configuring custom responses
  • Real-time Updates: Live synchronization with server state

4. REST API Control

  • Programmatic Control: Complete REST API for managing PyROS programmatically
  • Postman Integration: Pre-configured Postman collection for API testing
  • Endpoint CRUD Operations: Create, read, update, and delete endpoints via API
  • Response Management: Configure and manage custom responses through API calls

5. Testing Integration

  • Behave Step Definitions: Useful step definitions for behavior-driven testing
  • Mock Server Simulation: Simulate Postman-like behavior for OAS files
  • Development Tool: Designed specifically for software testing scenarios

Usage Instructions

Docker Deployment

  1. Build: docker compose build pyros
  2. Run Server: docker compose up pyros
  3. Access GUI: docker exec -it pyros bash & ./scripts/start_pyros_gui.sh

Using the GUI

  1. Connect: Enter server URL (default: http://127.0.0.1:6767)
  2. Load OAS File: Browse and load OpenAPI Specification YAML file
  3. Generate Endpoints: Click "Load" to automatically generate endpoints from OAS file
  4. Manage Endpoints: View all registered endpoints in the endpoint list
  5. Configure Responses:
    • Select an endpoint
    • Click "Add Custom Response"
    • Configure HTTP status code and JSON body
  6. Test Endpoints: Use the configured endpoints for testing your applications

Using the REST API

  1. Add Endpoint: POST to /add_dynamic_endpoint with URL and methods
  2. Set Custom Response: POST to /add_custom_response with endpoint, method, status code, and body
  3. List Endpoints: GET /list_endpoints to view all registered endpoints
  4. List Custom Responses: GET /list_custom_responses to view all custom responses
  5. Simulate Postman: POST to /simulate_postman with OAS file path to auto-generate endpoints

Technical Highlights

Architecture

  • Modular Design: Clear separation of concerns with dedicated classes for each responsibility
  • Dynamic Routing: FastAPI dynamic routing for flexible endpoint registration
  • Template Matching: Intelligent URL template matching with variable substitution
  • Threading Support: Concurrent operations for non-blocking server management

OAS Processing

  • Automatic Parsing: Extract endpoint definitions, methods, and URL parameters from OAS files
  • Enum Support: Handle enum definitions in path parameters
  • Schema Validation: Process OpenAPI schema definitions

Docker Integration

  • Containerized Deployment: Easy portability and environment isolation
  • Volume Mounting: OAS files can be mounted at /data for easy access
  • X11 Forwarding: GUI support for remote desktop environments

PyROS - Mock REST APIs dynamically from OpenAPI Specifications.