🛠 Как проектировать REST API: полезные советы для разработчика

1. Используйте существительные во множественном числе для обозначения коллекций.

# Хорошо
GET /products         
GET /products/{product_id} 

# Плохо
GET /product/{product_id}

2. Не добавляйте ненужные пути в структуру URL-адресов.

# Хорошо
GET /v3/application/listings/{listing_id}

# Плохо
PATCH /v3/application/shops/{shop_id}/listings/{listing_id}

3. Не добавляйте .json или другие расширения к URL-адресу.

4. Не возвращайте массивы в качестве ответов верхнего уровня от эндпоинтов. Верхний уровень ответа должен быть объектом, а не массивом, чтобы обеспечить обратную совместимость и возможность добавления пагинации.

# Хорошо
GET /things returns:
{ "data": [{ ...thing1...}, { ...thing2...}] }

# Плохо
GET /things returns:
[{ ...thing1...}, { ...thing2...}]

5. Не возвращайте структуры map. Вместо этого используйте массивы объектов, чтобы избежать проблем при работе с типизированными языками и не усложнять обработку данных.

# Хорошо
GET /things returns:
{
    "data": [
        { "id": "KEY3", "foo": "bat" }
    ]   
}

# Плохо
GET /things returns:
{
    "KEY3": { "id": "KEY3", "foo": "bat" }
}

6. Используйте строки для всех идентификаторов.

# Хорошо
{ "id": "123" }

# Плохо
{ "id": 123 }

7. Добавляйте префиксы к идентификаторам. Это улучшает читаемость API и помогает различать разные типы идентификаторов.

8. Не используйте 404 для обозначения "not found". Вместо этого рекомендуется использовать другие коды ошибок, чтобы точно указать на отсутствие ресурса.

9. Будьте последовательными. Несоответствие в схемах и структурах может вызвать путаницу и усложнить работу с API.

10. Используйте структурированный формат ошибок. Это облегчает отладку и обработку ошибок на разных уровнях системы.

11. Обеспечьте механизмы идемпотентности. Это важно для предотвращения дублирования операций в условиях нестабильной сети.

12. Используйте строки ISO8601 для временных меток. Строковое представление времени более читаемо и удобно для работы.

👉 Подробнее

#проектирование_систем

🤖 Напоминаем, что у нас есть еженедельная email-рассылка, посвященная последним новостям и тенденциям в мире искусственного интеллекта.

В ней:
● Новости о прорывных исследованиях в области машинного обучения и нейросетей
● Материалы о применении ИИ в разных сферах
● Статьи об этических аспектах развития технологий
● Подборки лучших онлайн-курсов и лекций по машинному обучению
● Обзоры инструментов и библиотек для разработки нейронных сетей
● Ссылки на репозитории с открытым исходным кодом ИИ-проектов
● Фильмы, сериалы и книги

👉Подписаться👈

🤷‍♂️ «Питомцы vs Скот»: 99% вашей работы в итоге выбросят, но это и сделает вас профи

Раньше в DevOps, когда каждый сервер был уникален и имел свое имя (как домашний питомец), админы уделяли много внимания каждому серверу. Если сервер падал, его восстанавливали (лечили больного питомца).

Современный подход к серверам больше похож на управление стадом скота: если один сервер выходит из строя, его заменяют новым. Это стало возможным благодаря развитию облачных технологий.

Может разработчикам тоже стоит изменить свое отношение к коду и проектам? Вместо того чтобы относиться к каждой строке кода, как к домашнему питомцу (с бесконечными рефакторингами и заботой), нужно принять, что большая часть кода со временем станет ненужной и будет заменена.

Это поможет избежать выгорания, ведь ты осознаешь, что твоя работа — это решение текущих задач бизнеса.

И хоть с 99-ю процентами автор загнул (хотя кто знает), это весьма любопытная аналогия.

🤖 «Генеративный ИИ для начинающих» — новый курс от Microsoft, который включает 12 уроков от Microsoft Cloud Advocates. Каждый урок охватывает ключевые аспекты принципов генеративного ИИ и разработки приложений и включает:

☑️ Видеообзор темы
☑️ Текстовая лекция
☑️ Jupyter Notebook с примерами кода
☑️ Задание для самостоятельной работы
☑️ Ссылки на полезные ресурсы

🥷Это путь воина

Напоминаем, что «Библиотека программиста» запустила два новых канала специально для специалистов по C++ и тех, кто хочет ими стать👨‍🏫

Подписывайтесь:
👉Библиотека собеса по C++ — тут мы готовимся к интервью
👉Библиотека задач по C++ — тут решаем задачи, проходим тесты и изучаем код

🤩 Ребята из Honeypot продолжают снимать замечательные доки про языки программирования, популярные технологии, библиотеки и инструменты. Из последнего — Ruby on Rails.

Ruby on Rails (Rails) — один из самых обсуждаемых полнофункциональных фреймворков, который за 20 лет превратился из «сумасшедшей идеи» в ключевой инструмент в мире веб-разработки. Основатель Rails, датский программист Давид Хейнемейер Ханссон, известный как DHH, является одной из самых спорных и влиятельных фигур в сообществе. Он рассказывает о том, как Rails развивался и менялся.

Вас ждут интервью с ключевыми фигурами Rails, которые делятся историей языка и фреймворка, страстью, противостоянием и зрелостью, наступившей после выпуска Rails 3.0.

📌 Другие доки:
📺 React.js
📺 Prometheus
📺 Kubernetes: часть 1 & часть 2
📺 Vue.js
📺 GraphQL
📺 Elixir
📺 Ember.js

❗️Мы запускаем серию исследований — и вы можете нам в этом помочь!

«Библиотека программиста» выпустит несколько статей, в которых мы проведем полноценные исследования.

Помогите нам выбрать интересные темы: может быть, вы давно хотели узнать, как изменилась зарплата у тех, кто релоцировался? Или гадаете, сколько лет нужно, чтобы стать миддлом?

Присылайте интересующие вас темы в комментарии — интересные мы возьмем в работу и поделимся с вами результатами 💙

📌 То, что зацепило на это неделе:

🤯 Как сооснователя Сэма Альтмана уволили с поста СЕО, а затем вернули обратно: разбор истории.
🤩 Dota 2 стала образовательной дисциплиной по стратегии в Филиппинском университете.
🤩 DALL-E 3 заработала в Paint для всех пользователей Windows 11.

🔸 Опубликован выпуск IDE Qt Creator 12.0, предназначенной для создания кроссплатформенных приложений с использованием Qt.
🔸 Представлен релиз PHP 8.3. Новая ветка включает ряд новых возможностей, а также несколько изменений, нарушающих совместимость.
🔸 Доступен выпуск Git 2.43. О новых фичах на русском читайте здесь.
🔸 Состоялся релиз Firefox 120. Новый выпуск поддерживает операцию Copy Link Without Site Tracking, позволяющую скопировать URL выбранной ссылки, предварительно вырезав из него опции, которые используются для отслеживания переходов. Читайте подробнее об этой и многих других фичах на русском.
🔸 В репозитории PyPI выявлено около 5000 оставленных в коде секретов и 8 вредоносных обфускаторов.

#чтопроисходит

🛠 Обзор GitHub на некоторые из наиболее интересных функций и изменений Git (обзор от OpenNET)

▫️В команду git repack добавлены опции "--filter" и "--filter-to", позволяющие выполнить переупаковку репозитория c учётом заданного фильтра объектов, и при необходимости перенести в отдельное место объекты, не удовлетворяющие заданному фильтру.

▫️Например для оставления в репозитории блобов, размером менее 1 МБ, и выносом в отдельный репозиторий остальных крупных объектов, можно выполнить:

$ git init --bare ../backup.git
$ git repack -ad --filter='blob:limit=1m' \
   --filter-to=../backup.git/objects/pack/pack

▫️Инициализация репозитория при помощи частичного клонирования позволяет работать с неполной копией репозитория, корректно обрабатывая обращения к отсутствующим объектам (при обращении к отсутствующим объектам, они на лету будут загружаться по мере необходимости).

$ git clone --filter=tree:0 git@github.com:git/git.git

▫️Добавлена возможность работы (git repack --max-cruft-size) с несколькими pack-файлами с информацией о недостижимых объектах (cruft packs), на которые в репозитории отсутствуют ссылки (не ссылаются ветки или теги).

▫️Добавлено распознавание попыток выполнения двойной отмены коммита через git revert и учёт этого факта при формировании сообщения об отмене

$ git revert --no-edit HEAD >/dev/null
$ git revert --no-edit HEAD >/dev/null
$ git log --oneline
a300922 (HEAD -> main) Reapply "fix bug"
0050730 Revert "fix bug"
b290810 fix bug

▫️Разрешено совместное использование опций "--rfc" и "--subject-prefix". Например, для формирования письма с префиксом "[RFC PATCH bpf-next]" в теме сообщения можно указать:

$ git format-patch --subject-prefix="PATCH bpf-next" --rfc

▫️В команде git log разрешено указание заполнителя "%(decorate)" для показа имён связанных веток при определении формата при помощи опции "--format", например:

$ git log --format='%cr%(decorate) (%h) %s'

#новости #инструменты