🎭 fake-usos

fake-usos is a mock implementation of the USOS API based on usos4j. It lets you simulate a USOS API server locally, making it easier to develop and test your applications without needing access to a real university USOS instance.

---

🚨 Why fake-usos?

Access to the real USOS API is becoming increasingly restricted:

• 🔒 Many universities now limit access to employees only.
• 📝 Even for development environments, prior verification is required and involves substantial paperwork.
• 🚫 As a result, it's getting harder to build new apps that rely on USOS data.

fake-usos provides a simple solution - a fake but schema-compliant USOS API that developers can run locally or in CI/CD pipelines.

🛠 Features

• 🎯 Simulates USOS API endpoints
• 🧩 Compatible with usos4j and similar clients
• 🔁 Returns realistic mock data
• ⚙️ Automatically stubs out endpoints based on usos4j
• 🔍 Covers only the endpoints implemented in usos4j
• 🧪 Works great for local development and automated tests
• 🐳 Runs easily in Docker

🤖 Smart Stub Generation

One of the challenges of working with USOS is the lack of an OpenAPI specification or structured API documentation.

To address this, fake-usos infers the supported endpoints directly from usos4j — a widely-used Java client for USOS.

As usos4j grows and implements more endpoints, fake-usos automatically creates stubs for them. This ensures API compatibility and saves time maintaining fake responses manually.

🔒 Note: fake-usos only covers endpoints available in usos4j. If you're using USOS features not implemented in usos4j, they won't be available in fake-usos either - by design.

🚀 Getting Started

🐳 Run with Docker

No need for Java, Maven, or Gradle. Just build and run the Docker image:

git clone https://github.com/WMS-DEV/fake-usos.git
cd fake-usos

# Build the Docker image
docker build -t fake-usos .

# Run the container
docker run -p 8080:8080 fake-usos

🔍 Example Request & Response

GET /services/timetable/classgroups

[
    {
        "type": "classgroup2",
        "start_time": "2025-06-22 18:54:28",
        "end_time": "2025-06-22 18:54:28",
        "name": {
            "pl": "272JkSluIu",
            "en": "i427EasgGn"
        },
        "url": "classgroup2"
    },
    {
        "type": "classgroup2",
        "start_time": "2025-06-22 18:54:28",
        "end_time": "2025-06-22 18:54:28",
        "name": {
            "pl": "c2Tz3VSqRO",
            "en": "RR58iMZ4wU"
        },
        "url": "classgroup2"
    },
    {
        "type": "classgroup2",
        "start_time": "2025-06-22 18:54:28",
        "end_time": "2025-06-22 18:54:28",
        "name": {
            "pl": "dEnGodhxjs",
            "en": "VZCjyGSwfP"
        },
        "url": "classgroup2"
    },
    {
        "type": "classgroup2",
        "start_time": "2025-06-22 18:54:28",
        "end_time": "2025-06-22 18:54:28",
        "name": {
            "pl": "lqpOdvsNiA",
            "en": "O5ellQgwpP"
        },
        "url": "classgroup2"
    },
    {
        "type": "classgroup2",
        "start_time": "2025-06-22 18:54:28",
        "end_time": "2025-06-22 18:54:28",
        "name": {
            "pl": "onajiK11qc",
            "en": "dgi9wsYjHe"
        },
        "url": "classgroup2"
    }
]