Рубрики
Uncategorized

Создание надежных и простых в использовании API с API First Design

Недавно мне пришлось создать шлюз API для клиента. Идет из фона разработчика, API Desi … Tagged с DevOps, WebDev, AWS, API.

API First Design (2 серии деталей)

Недавно мне пришлось создать шлюз API для клиента. Исходя из опыта разработчика, дизайн API был для меня запоздалой мыслью. Как только я закончил с пользовательскими историями, я написал свою схему базы данных, чтобы я мог продолжить кодирование веб -приложения. API развивается органично, из того, что имеет смысл в то время.

Но, как я узнал в проекте, API — это интерфейсы между людьми (столько же, сколько между системами). Сознательно думать о вашем дизайне API и последовательность в этих дизайнерских решениях помогает вашим конечным пользователям изучать ваши API быстрее и с минимальными усилиями. Кроме того, ваши конечные пользователи полагаются на ваши API для создания приложений. Разрыв изменения в этих API означает время простоя для приложений вашего конечного пользователя.

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

Таким образом, процесс выглядит так:

  • Часть 1-Создайте надежные и простые в использовании API с API First Design (Current Post)
    • Начните с цели
    • Создайте пользовательские истории
    • Создайте модели доменов
    • Нарисуйте свои API
  • Часть 2 — Определите контракты API с Swagger/OpenAPI
    • Напишите определение OpenAPI
    • Начать развиваться
    • Обработка изменений дизайна API

Используя определения OpenAPI 3.0 в качестве «контрактов» между разработчиком API и его/ее конечными пользователями, определяется единственный источник истины о том, как должен работать API. С этим «контрактом», определяющим, как работает каждая конечная точка API, мы защищаем от внезапных незапланированных изменений API.

Давайте рассмотрим процесс проектирования для простого приложения лояльности, которое мы будем создавать для ресторанов.

[1] Начните с цели

Наша цель для приложения для лояльности состоит в том, чтобы партнерские рестораны создавали карты лояльности для клиентов и для клиентов, чтобы иметь возможность зарабатывать очки и выкупить товары своими очками.

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

[2] Создание пользовательских историй

Имея в виду эту цель, давайте подробно рассмотрим возможности нашего приложения лояльности, используя пользовательские истории:

  • Как конечный пользователь:
    • Я могу зарегистрироваться на карту лояльности онлайн
    • Я могу войти
    • Я могу заработать очки с каждой транзакцией с рестораном -партнером
    • Я могу просматривать баланс своих очков в Интернете
    • Я могу просматривать историю транзакций онлайн
    • Я могу просмотреть конкретные транзакции, которые я сделал
  • Как менеджер ресторана:
    • Я вижу регистрацию онлайн -карт для моего ресторана
    • Я могу распечатать карту для каждой регистрации
    • Я могу отметить карту, как утверждается
    • Я могу просматривать транзакции, завершенные с картой лояльности для моего ресторана
    • Я могу использовать пункты пользователя для сделки
  • Как пользователь администратора:
    • Я могу создать рестораны

[3] Создайте модели доменов

Создание ваших доменных моделей — это процесс перевода ваших пользовательских историй в объекты. Эти объекты имеют атрибуты и поведение. Думайте об этих классах как о классах в парадигме объектно-ориентированного программирования (ООП).

С объектами, давайте подумаем об их отношениях друг с другом:

  • У пользователя может быть много карт
  • Карта может иметь много транзакций
  • Партнеры могут завести много карт (они могут продать столько карт лояльности, сколько захотят)
  • У партнеров может быть много транзакций

Чтобы ввести в действие эти отношения, мы представим концепцию «иностранного ключа». С иностранным ключом мы добавляем поле {object_name} _id к объекту в правой стороне отношений. Для отношений «пользователь может иметь много карт», мы добавляем поле user_id на объекте карты.

[4] Нарисуйте свои API

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

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

Понимание конечных точек API

Чтобы вызвать API, отправьте запрос на сервер со следующими компонентами:

  • Базовый URL: лояльность-app.com
  • Путь:/Карты
    • То, как мы строим наши пути, определяет, каким образом будет наше макет ресурсов. Альтернативный макет ресурса для ресурса карты — это гнездо его с помощью пользовательского ресурса, такого как/пользователи/10/карты.
  • Метод http: ПОЛУЧИТЬ
  • Параметры запроса:
  • Запросить тело:
    • Он используется для Post и других методов HTTP, но не получается.
  • заголовки

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

  • ПОЛУЧИТЬ

Лучшие практики API

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

Стандартные методы

  • Стандартные методы позволяют API иметь постоянный набор методов в разных ресурсах.
    • Стандартные методы созданы узором после CRUD (создать, читать, обновить, удалить). Список стандартных методов доступен ниже.
    • Стандартные методы не должны иметь побочных эффектов. Он делает то, что говорит, не более того. Таким образом, мы можем иметь постоянный набор ожиданий во всех стандартных методах. Например, Пост/лояльность карты Конечная точка создает карту лояльности, она также не должна создавать транзакцию.
    • Предпочтительнее использовать патч через PUT при обновлении только определенных частей объекта.
    • Если вы не собираетесь реализовать все стандартные методы ресурса, вы все равно должны создавать для него конечную точку, но вернуть его HTTP 405 (метод не разрешен) или HTTP 403 (запрещен). Таким образом, ваш API последователен.

Пользовательские методы

  • Пользовательские методы позволяют создавать конечные точки с побочными эффектами. У него есть формат /{resource}/{id}: {custom_action}

    • Например, Post/лояльность-карты/10: претензия_Карда

Используйте коды состояния HTTP

  • Используйте коды статуса HTTP, чтобы сообщить о значении. Не все ошибки — ошибка 500, и не все успешные операции должны быть HTTP 200.
    • Http 200:
      • Http 201 (создано): после создания ресурса
      • Http 204 (без контента): после удаления ресурса
      • Http 200 (OK): улавливать все для успешной работы
    • Http 400: Пользовательская ошибка — пользователь попробовал что -то не так
      • Http 403 (запрещено): когда у вас нет доступа к ресурсу Вы получаете доступ
      • Http 404 (не найдено):
      • Http 400 (плохой запрос): проверьте полный список кодов HTTP 400, если его нет, используйте это в качестве всех.
    • HTTP 500: Ошибка сервера — ошибка с сервером
      • Http 500: Ошибка внутреннего сервера — в значительной степени улово всего для всех ошибок приложения.

Различный подход для длительных операций

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

Это краткое изложение руководящих принципов API. Если вы хотите узнать больше, я очень рекомендую книгу API дизайнерские шаблоны JJ Geewax.

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

Стандарт — конечные точки сбора

  • Создать — post/cards
  • Прочтите все — получить/карты

Стандарт — конечные точки ресурса

  • Прочтите один — get/cards/10
  • Обновить один (переопределить объект) — put/card/10
  • Обновите один (переопределите конкретные методы) — патч/карты/10
  • DELETE ONE — DELETE/CARD/10

Давайте применим то, что мы узнали

Наша задача теперь становится определяющей нашу макету ресурсов API и переводит методы каждого класса в конечную точку API.

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

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

В следующем посте мы будем создавать открытое определение API 3.0, чтобы определить детали каждой конечной точки API. С этим определением у нас может быть макет

Особая спасибо Аллену за то, что мои посты были более последовательными. Этот пост также стал возможным для авторов ниже, которые достали изучение API радости.

API First Design (2 серии деталей)

Оригинал: «https://dev.to/raphael_jambalos/develop-web-apps-faster-with-api-first-design-97e»

Читайте ещё по теме: