Аналитик на Балтике | Неверов Станислав

Проектирование 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

Please open Telegram to view this post

VIEW IN TELEGRAM

❤8👍7🔥5

www.group-telegram.com/es/BalticAnalyst.com/348

761 viewsedited  Apr 15 at 05:34

Проектирование 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