Какие знаешь способы проективания API?

Подходы к проектированию API

В зависимости от требований проекта, я использую несколько различных подходов к проектированию API:

REST (Representational State Transfer)

Мой основной подход — RESTful API. Это наиболее распространённый стиль для веб-сервисов:

Принципы REST:

• Ресурсо-ориентированность — URL представляют ресурсы (существительные во множественном числе)
• Стандартные HTTP методы — GET для чтения, POST для создания, PUT/PATCH для обновления, DELETE для удаления
• Stateless — каждый запрос содержит всю необходимую информацию
• Использование статус-кодов — 200 OK, 201 Created, 400 Bad Request, 404 Not Found, 500 Server Error

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel

app = FastAPI()

class User(BaseModel):
    id: int
    name: str
    email: str

@app.get("/users/{user_id}")
async def get_user(user_id: int):
    return {"id": user_id, "name": "John"}

@app.post("/users")
async def create_user(user: User):
    return {"id": 1, **user.dict()}

@app.put("/users/{user_id}")
async def update_user(user_id: int, user: User):
    return {"id": user_id, **user.dict()}

@app.delete("/users/{user_id}")
async def delete_user(user_id: int):
    return {"message": "User deleted"}

GraphQL

Для более сложных случаев, где клиенту нужно получить данные разных типов, использую GraphQL:

Преимущества GraphQL:

• Клиент запрашивает ровно те данные, которые ему нужны
• Один запрос вместо множества REST вызовов
• Строгая типизация
• Отличная документация

from strawberry import type, field
from typing import List

@type
class User:
    id: int
    name: str
    email: str

@type
class Query:
    @field
    def user(self, id: int) -> User:
        return User(id=id, name="John", email="john@example.com")
    
    @field
    def users(self) -> List[User]:
        return [
            User(id=1, name="John", email="john@example.com"),
            User(id=2, name="Jane", email="jane@example.com"),
        ]

gRPC

Для высоконагруженных систем с микросервисной архитектурой применяю gRPC:

Особенности:

• Использует Protocol Buffers для сериализации
• HTTP/2 протокол обеспечивает низкую latency
• Двусторонняя потоковая передача данных
• Отлично подходит для микросервисов

import grpc
from concurrent import futures

class UserServicer:
    def GetUser(self, request, context):
        return User(id=request.id, name="John", email="john@example.com")

def serve():
    server = grpc.server(futures.ThreadPoolExecutor(max_workers=10))
    server.add_insecure_port('[::]:50051')
    server.start()

WebSocket API

Для real-time коммуникации использую WebSocket:

from fastapi import WebSocket

@app.websocket("/ws/{client_id}")
async def websocket_endpoint(websocket: WebSocket, client_id: int):
    await websocket.accept()
    try:
        while True:
            data = await websocket.receive_text()
            await websocket.send_text(f"Message: {data}")
    except Exception as e:
        await websocket.close(code=1000)

Выбор подхода

Мой критерий выбора:

• REST — для CRUD операций, публичных API, простоты
• GraphQL — для сложных связанных данных, когда нужна гибкость
• gRPC — для микросервисов, высокой нагрузки и real-time систем
• WebSocket — для real-time уведомлений и чата

Важно помнить о версионировании API (/v1/, /v2/), документировании (OpenAPI/Swagger), валидации данных и безопасности (аутентификация, авторизация, rate limiting).