YOVI Interop API Contract (OpenAPI)

# YOVI Interop API Contract (OpenAPI)

## Context
During the Software Architecture course, each team is building a webapp to play the board game Y, including bot players.
One of the final goals is to run bot-vs-bot matches across teams, meaning our bots must be able to join a game hosted by a third-party team and play by sending/receiving moves through a public HTTP API.

## Problem
Right now, each team tends to expose a different API shape (or none at all), which makes cross-team bot competition expensive to integrate and easy to break.
We need a minimal, stable “interop contract” that teams can implement without sacrificing their internal architecture or forcing everyone to adopt the same codebase.

## Proposal
Introduce a _distilled_ interoperability API described as an OpenAPI 3.1 document (language-agnostic contract for HTTP APIs).
The goal is not to replace anyone’s internal API, but to provide a shared adapter surface that any team can implement and any bot can consume.

**OpenAPI doc**:
https://losadgm.github.io/yovi-interop-api/openapi.yml

**Swagger UI** (use for reference only; not the official documentation site of our Architecture project):
https://losadgm.github.io/yovi-interop-api/

## Design goals
- **Minimal required fields**: only properties marked as required must be implemented to be considered interop-compliant.

- **Easy to drive by a bot**: the bot can repeatedly (1) fetch game state, (2) propose a move, (3) receive the updated state + opponent response.

- **Extensible**: teams may add optional fields/schemas without breaking interop, as long as the required minimum remains unchanged and additions are documented.

## Contract at a glance (what interop expects)
### GET /games/{gameId}
Returns the current GameState snapshot (board size, layout in YEN notation, players, current turn, match status), plus relevant error codes for auth/permission/not found.

### POST /games/{gameId}/play
Client submits a PlayRequest containing the proposed new layout (YEN) after placing exactly one token; server validates legality, persists, and returns the resulting GameState (including the opponent’s “fast response” move, if the game is still ongoing).

## Authentication note (non-blocking)
The draft uses JWT bearer auth as an example, but any auth mechanism is acceptable if it doesn’t change the request/response schemas and is clearly documented by the implementing team.

## Open questions / feedback requested
- Are the two endpoints enough for interop, or do we need a third one (e.g., “create game”, “join game”, “list games”), or should those be explicitly out of scope?

- Are the error codes (NOT_PLAYING, NOT_YOUR_TURN) sufficient as a minimum set? Any other must-have codes?

- Does the status shape (ONGOING vs PLAYER_X_WINS) feel future-proof, or should it be normalized differently?

**If you review this, please be as critical as you want. This is intended as a draft proposal, and I’d rather adjust it now than have everyone implement something inconsistent later.**

Start by reviewing the linked OpenAPI 3.1 document at losadgm.github.io/yovi-interop-api/openapi.yml, focusing on GET /games/{gameId} and POST /games/{gameId}/play. Compare the required schemas, error codes, authentication note, and open questions; done means the interop scope and contract requirements are agreed and documented.

Written by the indexing model from the issue text.