S.E.O.R.A

S.E.O.R.A (Static Evaluator of RESTful APIs) is a research application developed for the study "Static Evaluation of RESTful APIs via OpenAPI" by Edwin Sundberg and Thea Ekmark.

Overview

S.E.O.R.A provides a platform for analyzing and evaluating RESTful APIs using their OpenAPI specifications. The tool statically inspects API definitions to identify best-practice violations, inconsistencies, and design issues, supporting both research and practical API quality assurance.

The project consists of a Python backend (FastAPI) and a React frontend (TypeScript, Vite, TailwindCSS).

Features

• Upload and analyze OpenAPI specifications
• Automated detection of common REST API design issues
• Interactive web interface for exploring violations and recommendations
• Extensible rule system for custom checks
• Fast, modern UI with dark mode support

Getting Started

Prerequisites

• Python 3.10+
• Node.js
• npm or yarn

Running with Docker (Recommended)

Prerequisites

• Docker installed

Environment Variable

You must set the MISTRAL_API_KEY environment variable for the backend to start. This is required for LLM-powered rule checks.

You can set it in your shell or in a .env file:

export MISTRAL_API_KEY=your_api_key_here

Or create a .env file in the project root:

MISTRAL_API_KEY=your_api_key_here

Build and Run (Backend + Frontend)

1. Build and start both backend and frontend using Docker Compose:

   docker compose up --build

   • The backend will be available at http://localhost:8000
   • The frontend will be available at http://localhost:5173

2. To stop the services:

   docker compose down

---

Manual Backend Setup (For Development)

1. Create and activate a virtual environment:

   python3 -m venv env
   source env/bin/activate

2. Install Python dependencies:

   pip install -r requirements.txt

3. Set the required environment variable:

   export MISTRAL_API_KEY=your_api_key_here

4. Run the FastAPI server:

   python -m fastapi_cli dev main.py

5. The backend will be available at http://localhost:8000 by default. See the FastAPI docs at http://localhost:8000/docs for the API documentation.

Frontend Setup

1. Install dependencies:

   cd client
   npm install

2. Start the development server:

   npm run dev

3. The frontend will be available at http://localhost:5173 by default.

Project Structure

• main.py — FastAPI backend entry point
• rules — Static analysis rules for OpenAPI specs
• client — React frontend

License

This project is licensed under the AGPL-3.0 License - see the LICENSE file for details.

Authors' Reserved Rights: Edwin Sundberg and Thea Ekmark each retain unlimited rights to their contributions to this project. Either author may independently:

• Relicense the entire codebase under any terms
• Use the code in proprietary or commercial projects
• Modify and redistribute without AGPL restrictions
• Grant sublicenses to third parties

This reservation of rights does not affect the AGPL-3.0 licensing of this public repository.