Agree on your hackathon API before frontend and backend split

When collaborating on an API for a frontend and backend split, it is crucial to agree on a unified response format before each team member begins working. This shared API contract, often a concise Markdown file, outlines the request structure, example JSON, and rules for handling empty results or errors. For a simple prototype, it can start with a route, JSON example, and clear guidelines for various outcomes.

In this example, the user action involves a teammate opening the task board and viewing tasks and their owners. To begin, the frontend requires a list, while the backend must consistently return the same fields. Therefore, the initial contract specifies:

Question: What data is needed for the task board demonstration?

Team decision: The backend must return an object containing an "items" array.

Response container: An object with an "items" array.

No tasks yet: { "items" : []}

Task identity: A non-empty, unique string ID.

Task title: A string with at least one non-space character.

Task owner: An assigned non-empty name or null.

Task state: The status must be either "todo" or "done."

For this prototype, a null assignee means the task has no owner. If your route returns private team data, include authentication and authorization requirements in the contract and enforce them on the server.

To facilitate the frontend's development, share three examples, including edge cases, alongside the successful response in the repository. Include the empty response, { items : []}, and error examples. Clearly define the error status and body for each anticipated failure. If a later search endpoint rejects malformed input, specify an HTTP 400 response with a custom error object. This ensures the frontend displays different states for "no tasks" and "could not load tasks" to help users understand the situation better.