Skip to content

API Documentation

This project uses FastAPI, which provides automatically generated API documentation using Swagger UI and ReDoc. You can access these interactive docs to explore the available endpoints, view request and response formats, and test the API.

Table of Contents

  1. Accessing the API Documentation
  2. Authentication for API Requests
  3. JWT Authentication with Cookies
  4. Using Swagger UI and ReDoc
  5. TypeScript API Client Code Generation
  6. Error Handling

Accessing the API Documentation

Once the FastAPI server is running, you can access the automatically generated API documentation via these URLs:

Both of these interfaces allow you to view all available endpoints, try out API requests, and see example responses.

Authentication for API Requests

The API uses JWT (JSON Web Token) authentication for securing certain endpoints. The authentication flow is managed by issuing JWT tokens and storing them in HTTP-only cookies, which are then used for subsequent requests. This provides a secure and stateless way to manage user sessions.

JWT Authentication with Cookies

  1. Login and JWT Token:

    • When a user logs in via the /api/auth/login endpoint, a JWT token is generated and returned in the response as an HTTP-only cookie (i.e., a cookie that is not accessible via JavaScript).
    • The JWT is stored in the jwt cookie and is used for authenticating subsequent requests.

  2. Request Authentication:

    • For every API request that requires authentication, the JWT token stored in the access_token cookie is automatically sent in the request headers.
    • You do not need to manually include the token in the Authorization header; the browser will handle the cookie-based authentication automatically.

  3. Logout:

    • To invalidate the JWT token and end the session, the user can call the /api/auth/logout endpoint. This will remove the access_token cookie, effectively logging the user out.

Example Authentication Flow:

  • Login:
curl -X POST http://localhost:8012/api/auth/login \
-H "Content-Type: application/json" \
-d '{"email": "[email protected]", "password": "password123"}'

On success, the server will set the jwt cookie in the response, which will be automatically used in subsequent API requests.

  • Authenticated Request:

Once the JWT cookie is set, any requests to authenticated endpoints (e.g., /api/items) will automatically include the JWT for authentication. You don't need to manually add the token.

  • Logout:
curl -X POST http://localhost:8012/api/auth/logout

This will clear the jwt cookie and log the user out.

Using Swagger UI and ReDoc

Swagger UI

Swagger UI provides a user-friendly interface where you can:

  • Explore all API endpoints.
  • Try out API requests directly from the browser.
  • View detailed request/response schemas.
  • Authenticate using a Bearer token or cookies.

To access Swagger UI, visit http://localhost:8012/docs.

ReDoc

ReDoc is another documentation style that presents the API in a structured, reference-friendly manner. It’s particularly useful for looking up specific endpoints or data models. To access ReDoc, visit http://localhost:8012/redoc.

TypeScript API Client Code Generation

On the front-end, you don’t need to worry about manually writing TypeScript interfaces for API requests and responses. The project includes a TypeScript code generation tool that automatically generates API client code and corresponding TypeScript interfaces based on the OpenAPI specification provided by FastAPI.

How It Works

  • The tool automatically fetches the openapi.json file from the FastAPI back-end (usually available at /openapi.json).
  • Based on this specification, the tool generates:
  • TypeScript interfaces for request/response types.
  • API client functions for making calls to each API endpoint.

This ensures that your front-end code always has up-to-date, type-safe API functions and data models, minimizing the chance of errors due to mismatched data structures.

Running the Codegen Tool

You can generate the TypeScript client and interfaces by running the following command on the front-end:

npm run generate-client

This will regenerate the API client and interfaces based on the latest openapi.json.

Error Handling

The API adheres to standard HTTP status codes to indicate the success or failure of a request:

  • 200: Successful request.
  • 201: Resource successfully created.
  • 400: Bad request (e.g., validation errors).
  • 401: Unauthorized (e.g., missing or invalid authentication token or cookie).
  • 404: Resource not found.
  • 500: Internal server error.

You can see specific error responses in the interactive docs, along with explanations for each error type.

By using the built-in Swagger UI and ReDoc, you have a comprehensive, interactive way to explore and understand the API. Authentication is handled securely through JWT tokens stored in HTTP-only cookies, and the TypeScript code generation tool automatically keeps your front-end in sync with the back-end API.