Что хотят услышать интервьюеры:

Ожидают понимания, что хороший API должен быть понятным, предсказуемым и удобным для потребителя. Важны единообразие, явные контракты, корректная обработка ошибок и обратная совместимость. Также ценится внимание к безопасности, производительности и возможности поддержки API в долгую.

Определение:

API проектируют как стабильный интерфейс взаимодействия между компонентами, где важны ясные правила, минимальная связанность и предсказуемое поведение. Основные принципы — простота, консистентность, версионирование, документация, безопасность и идемпотентность там, где это уместно. Хороший API позволяет клиенту пользоваться функциональностью без знания внутренних деталей реализации.

Пример использования:

Например, REST API для управления задачами может иметь предсказуемые эндпоинты: GET /tasks, POST /tasks, PUT /tasks/1, DELETE /tasks/1. Клиенту понятно, что чтение, создание, обновление и удаление выполняются разными HTTP-методами, а ошибки возвращаются в едином формате.

from flask import Flask, jsonify, request

app = Flask(__name__)

tasks = [{"id": 1, "title": "Write tests"}]

@app.get("/tasks")
def list_tasks():
    return jsonify(tasks), 200

@app.post("/tasks")
def create_task():
    data = request.get_json()
    task = {"id": len(tasks) + 1, "title": data["title"]}
    tasks.append(task)
    return jsonify(task), 201

Пояснение кода:

В примере показан простой API с двумя эндпоинтами. GET /tasks возвращает список задач и демонстрирует принцип предсказуемого чтения данных. POST /tasks принимает JSON, создаёт новую сущность и возвращает её с кодом 201 Created, что соответствует стандартному поведению API.

Ключевые моменты:

API должно быть простым и предсказуемым для потребителя.
Важна консистентность: одинаковые правила для именования, формата ответов и ошибок.
Контракт API нужно делать явным через документацию и понятные схемы данных.
Изменения стоит вносить с учётом обратной совместимости и версионирования.
Безопасность обязательна: аутентификация, авторизация, валидация входных данных.
Для операций важно учитывать корректные HTTP-методы, коды ответов и идемпотентность, если это применимо.

Какие основные принципы лежат в основе разработки API?