Проектирование API: от целей к REST API
REST API представляет свои цели, используя протокол HTTP. Цели переносятся в пары типа «ресурс и действие». Ресурсы идентифицируются путями, а действия представлены методами HTTP.
🔚Но как идентифицировать эти ресурсы и действия❓
🔚И как обозначать их, используя пути и методы HTTP❓
Мы делаем то, что всегда делалось при проектировании программного обеспечения — анализируем наши функциональные потребности для определения ресурсов и того, что с ними происходит, прежде чем переносить их в программное представление. Существует множество методов проектирования программного обеспечения, которые можно использовать для идентификации ресурсов и того, что можно с ними делать, основываясь на таких спецификациях, как таблица API-целей.
➖Рассмотри очень простой метод, состоящий из четырех этапов:
🔚Сначала мы должны идентифицировать ресурсы — функциональные концепции и их связь — как они организованы.
🔚Затем нужно определить доступные действия для каждого ресурса, их параметры и результаты.
🔚Как только это будет сделано, мы сможем перейти к фактическому проектированию программного интерфейса, создав пути к ресурсам.
🔚Затем выберем HTTP-методы для обозначения действий.
Смотрим схему.
Сейчас мы говорим только о номинальном случае, когда все в порядке – 200 OK.
➖Советы по проектированию
➡️Идентификация ресурсов:
🔚Пример ресурсов:
/users — пользователи
/orders — заказы.
🔚Пример связей:
Заказы принадлежат пользователю → /users/{userId}/orders.
➡️Важно:
🔚Используйте множественное число для имен ресурсов (/users, а не /user).
🔚Избегайте глаголов в путях (например, /getUsers — плохо).
➖Определение действий и параметров
🔚Для каждого ресурса продумайте:
🔚Какие действия возможны — CRUD: Create, Read, Update, Delete.
🔚Какие параметры передаются — в теле запроса, URL или заголовках.
🔚Что возвращает API — например, JSON-объект или статус.
➖Проектирование URL-путей
➡️Правила для URL:
🔚Иерархичность: /ресурс/{id}/подресурс.
🔚Пример: /users/{userId}/orders/{orderId}.
➡️Стабильность: Избегайте изменений путей после публикации API.
➡️Версионирование: Добавляйте версию в URL или заголовки
➖Выбор HTTP-методов
Сопоставьте методы HTTP с действиями:
Метод → Действие → Пример
GET → Чтение → GET /users
POST → Создание → POST /users
PUT → Полное обновление → PUT /users/{id}
PATCH → Частичное обновление → PATCH /users/{id}
DELETE → Удаление → DELETE /users/{id}
#аналитик #навыкАналитика #API #IT
REST API представляет свои цели, используя протокол HTTP. Цели переносятся в пары типа «ресурс и действие». Ресурсы идентифицируются путями, а действия представлены методами HTTP.
🔚Но как идентифицировать эти ресурсы и действия❓
🔚И как обозначать их, используя пути и методы HTTP❓
Мы делаем то, что всегда делалось при проектировании программного обеспечения — анализируем наши функциональные потребности для определения ресурсов и того, что с ними происходит, прежде чем переносить их в программное представление. Существует множество методов проектирования программного обеспечения, которые можно использовать для идентификации ресурсов и того, что можно с ними делать, основываясь на таких спецификациях, как таблица API-целей.
➖Рассмотри очень простой метод, состоящий из четырех этапов:
🔚Сначала мы должны идентифицировать ресурсы — функциональные концепции и их связь — как они организованы.
🔚Затем нужно определить доступные действия для каждого ресурса, их параметры и результаты.
🔚Как только это будет сделано, мы сможем перейти к фактическому проектированию программного интерфейса, создав пути к ресурсам.
🔚Затем выберем HTTP-методы для обозначения действий.
Смотрим схему.
Сейчас мы говорим только о номинальном случае, когда все в порядке – 200 OK.
➖Советы по проектированию
➡️Идентификация ресурсов:
🔚Пример ресурсов:
/users — пользователи
/orders — заказы.
🔚Пример связей:
Заказы принадлежат пользователю → /users/{userId}/orders.
➡️Важно:
🔚Используйте множественное число для имен ресурсов (/users, а не /user).
🔚Избегайте глаголов в путях (например, /getUsers — плохо).
➖Определение действий и параметров
🔚Для каждого ресурса продумайте:
🔚Какие действия возможны — CRUD: Create, Read, Update, Delete.
🔚Какие параметры передаются — в теле запроса, URL или заголовках.
🔚Что возвращает API — например, JSON-объект или статус.
➖Проектирование URL-путей
➡️Правила для URL:
🔚Иерархичность: /ресурс/{id}/подресурс.
🔚Пример: /users/{userId}/orders/{orderId}.
➡️Стабильность: Избегайте изменений путей после публикации API.
➡️Версионирование: Добавляйте версию в URL или заголовки
➖Выбор HTTP-методов
Сопоставьте методы HTTP с действиями:
Метод → Действие → Пример
GET → Чтение → GET /users
POST → Создание → POST /users
PUT → Полное обновление → PUT /users/{id}
PATCH → Частичное обновление → PATCH /users/{id}
DELETE → Удаление → DELETE /users/{id}
#аналитик #навыкАналитика #API #IT