Глава 10. API-интерфейсы данных JSON и приложения на основе гипермедиа

---

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

Однако сегодня мы должны признать, что многие веб-приложения часто создаются без использования этого подхода. Вместо этого они используют интерфейсную библиотеку одностраничного приложения, такую ​​как React, для создания своего приложения и взаимодействуют с сервером через JSON API. Этот JSON API почти никогда не использует концепции гипермедиа. Скорее API-интерфейсы JSON, как правило, являются API-интерфейсами данных , то есть API, который просто возвращает клиенту структурированные данные домена без какой-либо информации управления гипермедиа. Сам клиент должен знать, как интерпретировать данные JSON: какие конечные точки связаны с данными, как следует интерпретировать определенные поля и так далее.

Теперь, хотите верьте, хотите нет, мы создаем API для Contact.app.

Это может показаться вам запутанным: API? Мы только что создали веб-приложение с обработчиками, которые просто возвращают HTML.

Как это API?

Оказывается, Contact.app действительно предоставляет API. Просто это гипермедийный API, который понимает гипермедийный клиент , то есть браузер. Мы создаем API для взаимодействия браузера через HTTP, и благодаря магии HTML и гипермедиа браузеру не нужно ничего знать о нашем API гипермедиа, кроме URL-адреса точки входа: все действия и отображаемая информация. поставляется автономно в ответах HTML.

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

API-интерфейсы Hypermedia и API-интерфейсы данных JSON

Итак, у нас есть гипермедийный API для Contact.app. Должны ли мы также включить API данных для Contact.app?

Конечно! Существование API гипермедиа никоим образом не означает , что у вас не может быть API данных. Фактически, это обычная ситуация в традиционных веб-приложениях: есть «веб-приложение», вход в который осуществляется через URL-адрес точки входа, скажем https://mywebapp.example.com/. А еще есть отдельный JSON API, доступный через другой URL, например https://api.mywebapp.example.com/v1.

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

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

Например:

• Возможно, у вас есть мобильное приложение, созданное без использования Hyperview. Этому приложению нужно будет каким-то образом взаимодействовать с вашим сервером, и использование существующего HTML API почти наверняка не подойдет! Вам нужен программный доступ к вашей системе через API данных, и JSON — естественный выбор для этого.

• Возможно, у вас есть автоматизированный скрипт, которому необходимо регулярно взаимодействовать с системой. Например, возможно, у нас есть задание массового импорта, которое выполняется каждую ночь и требует импорта/синхронизации тысяч контактов. Хотя это можно было бы написать в сценарии с использованием HTML API, это также было бы раздражающим: синтаксический анализ HTML в сценариях подвержен ошибкам и утомителен. Для этого варианта использования было бы лучше иметь простой JSON API.

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

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

"Что!?! Вы хотите, чтобы я разобрал HTML!?!!»

Путаница, с которой мы часто сталкиваемся в онлайн-дискуссиях, когда защищаем гипермедийный подход к созданию веб-приложений, заключается в том, что люди думают, что мы имеем в виду, что они должны анализировать HTML-ответы с сервера, а затем выгружать данные в свою структуру SPA или мобильные приложения.

Это, конечно, глупо.

Вместо этого мы имеем в виду, что вам следует рассмотреть возможность использования API гипермедиа с клиентом гипермедиа , например браузером, интерпретирующим сам ответ гипермедиа и представляющим его пользователю. Гипермедийный API нельзя просто приварить к существующему подходу SPA. Для эффективного использования требуется сложный гипермедийный клиент, такой как браузер.

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

Различия между API-интерфейсами Hypermedia и API-интерфейсами данных

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

Не является ли излишним наличие обоих типов API для нашего приложения?

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

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

Давайте сравним потребности API JSON с API Hypermedia:

Требования к JSON API	Гипермедийный API
Он должен оставаться стабильным с течением времени: вы не можете менять API волей-неволей, иначе вы рискуете сломать клиенты, которые используют API и ожидают, что определенные конечные точки будут вести себя определенным образом.	Нет необходимости сохранять стабильность с течением времени: все URL-адреса обнаруживаются через ответы HTML, поэтому вы можете гораздо более агрессивно изменять форму API гипермедиа.
Он должен иметь версию: что касается первого пункта, когда вы вносите серьезные изменения, вам необходимо изменить версию API, чтобы клиенты, использующие старый API, продолжали работать.	Управление версиями не является проблемой, это еще одна сильная сторона подхода гипермедиа.
Скорость должна быть ограничена: поскольку API данных часто используются другими клиентами, а не только вашим собственным внутренним веб-приложением, скорость запросов должна быть ограничена, часто пользователем, чтобы избежать перегрузки системы одним клиентом.	Ограничение скорости, вероятно, не так важно, как предотвращение атак распределенного отказа в обслуживании (DDoS).
Это должен быть общий API: поскольку API предназначен для всех клиентов, а не только для вашего веб-приложения, вам следует избегать специализированных конечных точек, которые определяются потребностями вашего собственного приложения. Вместо этого API должен быть достаточно общим и выразительным, чтобы удовлетворить как можно больше потенциальных потребностей клиентов.	API может быть очень специфичным для нужд вашего приложения: поскольку он предназначен только для вашего конкретного веб-приложения и поскольку API обнаруживается через гипермедиа, вы можете добавлять и удалять тщательно настроенные конечные точки для конкретных функций или потребностей оптимизации в вашем приложении.
Аутентификация для такого рода API обычно основана на токенах, о которых мы поговорим более подробно позже.	Аутентификация обычно управляется с помощью файла cookie сеанса, установленного на странице входа.

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

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

Это ключевое преимущество отделения API данных от API Hypermedia.

API-интерфейсы данных .JSON и API-интерфейсы JSON «REST»

К сожалению, сегодня по историческим причинам то, что мы называем API-интерфейсами данных JSON, в отрасли часто называют «REST API». Это иронично, потому что при любом разумном прочтении работы Роя Филдинга, определяющего, что означает REST, подавляющее большинство API-интерфейсов JSON не являются RESTful . Даже не близко.

Меня расстраивает количество людей, называющих любой HTTP-интерфейс REST API. Сегодняшний пример — REST API SocialSite. Это РПК. Это кричит RPC. Здесь так много взаимосвязи, что ей следует присвоить рейтинг X.

Что нужно сделать, чтобы в архитектурном стиле REST было ясно, что гипертекст является ограничением? Другими словами, если механизм состояния приложения (и, следовательно, API) не управляется гипертекстом, то он не может быть RESTful и не может быть REST API. Период. Есть ли где-нибудь сломанное руководство, которое нужно починить?

— Рой Филдинг, https://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven

История того, как «REST API» в отрасли стала означать «JSON API», длинная и грязная, и выходит за рамки этой книги. Однако, если вам интересно, вы можете обратиться к эссе одного из авторов этой книги под названием «Как REST стал означать противоположность REST?» на сайте htmx .

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

Добавление API данных JSON в Contact.app

Хорошо, как мы добавим API данных JSON в наше приложение? Один из подходов, популяризированный веб-инфраструктурой Ruby on Rails, заключается в использовании тех же конечных точек URL-адресов, что и в вашем гипермедийном приложении, но с использованием заголовка HTTP, Acceptчтобы определить, хочет ли клиент представление JSON или представление HTML. Заголовок HTTP Acceptпозволяет клиенту указать, какие типы многоцелевых расширений почты Интернета (MIME), то есть типы файлов, он хочет получить от сервера: JSON, HTML, текст и т. д.

Итак, если клиенту нужно представление всех контактов в формате JSON, он может отправить запрос GET, который выглядит следующим образом:

Accept: application/json

GET /contacts

Если бы мы приняли этот шаблон, то наш обработчик запросов /contacts/необходимо было бы обновить, чтобы он проверял этот заголовок и, в зависимости от значения, возвращал JSON, а не HTML-представление для контактов. Ruby on Rails поддерживает этот шаблон, встроенный в инфраструктуру, что позволяет очень легко включить запрошенный тип MIME.

К сожалению, наш опыт работы с этим шаблоном не был большим по причинам, которые должны быть ясны, учитывая различия, которые мы обрисовали между API данных и гипермедиа: они имеют разные потребности и часто принимают совершенно разные «формы», и пытаются втиснуть их в один и тот же набор URL-адресов в конечном итоге создает большую напряженность в коде приложения.

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

Выбор корневого URL-адреса для нашего API

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

Оглядываясь вокруг, можно сказать, что многие места используют поддомен для своих API, что-то вроде https://api.mywebapp.example.comи, по сути, часто кодируют управление версиями в поддомене: https://v1.api.mywebapp.example.com.

Хотя это имеет смысл для крупных компаний, для нашего скромного маленького приложения Contact.app это кажется излишним. Вместо использования поддоменов, которые усложняют локальную разработку, мы будем использовать подпути внутри существующего приложения:

• Мы будем использовать /apiв качестве корня для нашей функциональности API данных

• Мы будем использовать /api/v1в качестве точки входа для версии 1 нашего API данных.

Если и когда мы решим обновить версию API, мы сможем перейти к /api/v2и так далее.

Этот подход, конечно, не идеален, но он будет работать для нашего простого приложения и может быть адаптирован к субдоменному подходу или различным другим методам позже, когда наше приложение Contact.app захватит Интернет и мы сможем позволить себе большая команда разработчиков API. :)

Наша первая конечная точка JSON: список всех контактов

Давайте добавим нашу первую конечную точку Data API. Он будет обрабатывать HTTP- GETзапрос /api/v1/contactsи возвращать список всех контактов в системе в формате JSON. В некотором смысле это будет похоже на наш исходный код для маршрута гипермедиа /contacts: мы загрузим все контакты из базы данных контактов, а затем отобразим некоторый текст в качестве ответа.

Мы также собираемся воспользоваться приятной особенностью Flask: если вы просто возвращаете объект из обработчика, он сериализует (то есть преобразует) этот объект в ответ JSON. Это позволяет очень легко создавать простые API-интерфейсы JSON в flask!

@app.route("/api/v1/contacts", methods=["GET"]) (1)
def json_contacts():
    contacts_set = Contact.all()
    contacts_dicts = [c.__dict__ for c in contacts_set] (2)
    return {"contacts": contacts_dicts} (3)

1. JSON API имеет собственный путь, начинающийся с /api.

2. Преобразуйте массив контактов в массив простых объектов словаря (карты).

3. Верните словарь, содержащий contactsсвойства всех контактов.

Этот код Python может показаться вам немного странным, если вы не являетесь разработчиком Python, но все, что мы делаем, — это преобразуем наши контакты в массив простых пар имя/значение и возвращаем этот массив во включающем объекте в качестве свойства contacts . Flask автоматически сериализует этот объект в ответ JSON.

При этом, если мы отправим HTTP- GETзапрос к /api/v1/contacts, мы увидим ответ, который выглядит примерно так:

{
  "contacts": [
    {
      "email": "[e-mail]",
      "errors": {},
      "first": "Carson",
      "id": 2,
      "last": "Gross",
      "phone": "123-456-7890"
    },
    {
      "email": "[e-mail]",
      "errors": {},
      "first": "",
      "id": 3,
      "last": "",
      "phone": ""
    },
    ...
  ]
}

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

• Перемещайте свои контакты в другую систему каждую ночь.

• Резервное копирование контактов в локальный файл

• Автоматизируйте рассылку электронных писем своим контактам

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

Добавление контактов

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

В веб-приложении нам нужен был отдельный путь /contacts/newдля размещения HTML-формы для создания нового контакта. В веб-приложении мы приняли решение указать POSTтот же путь, чтобы обеспечить согласованность.

В случае с JSON API такой путь не требуется: JSON API «просто есть»: ему не нужно предоставлять какое-либо гипермедийное представление для создания нового контакта. Вы просто знаете, где отправить команду POSTдля создания контакта (вероятно, через некоторую документацию, предоставленную об API), и все.

По этой причине мы можем поместить обработчик «создать» по тому же пути, что и обработчик «списка»: /api/v1/contacts, но заставить его отвечать только на HTTP- POSTзапросы.

Код здесь относительно прост: заполните новый контакт информацией из запроса POST, попытайтесь сохранить его и — если это не удалось — отобразите сообщения об ошибках. Вот код:

@app.route("/api/v1/contacts", methods=["POST"]) (1)
def json_contacts_new():
    c = Contact(None, request.form.get('first_name'), request.form.get('last_name'), request.form.get('phone'),
                request.form.get('email')) (2)
    if c.save(): (3)
        return c.__dict__
    else:
        return {"errors": c.errors}, 400 (4)

1. Этот обработчик находится на том же пути, что и первый для нашего JSON API, но обрабатывает POSTзапросы.

2. Мы создаем новый контакт на основе значений, отправленных вместе с запросом.

3. Мы пытаемся сохранить контакт и, в случае успеха, отобразить его как объект JSON.

4. Если сохранение не удалось, мы отображаем объект, показывающий ошибки, с кодом ответа 400 (Bad Request).

В некотором смысле это похоже на наш contacts_new()обработчик из нашего веб-приложения; мы создаем контакт и пытаемся его сохранить. В остальном все совсем иначе:

• При успешном создании здесь не происходит перенаправления, поскольку мы не имеем дело с таким гипермедийным клиентом, как браузер.

• В случае неправильного запроса мы просто возвращаем код ответа об ошибке 400 (Bad Request). В этом отличие от веб-приложения, где мы повторно отображаем форму с сообщениями об ошибках.

Подобные различия со временем накапливаются и делают идею сохранения JSON и API-интерфейсов гипермедиа на одном и том же наборе URL-адресов все менее и менее привлекательной.

Просмотр сведений о контакте

Далее давайте предоставим клиенту JSON API возможность загружать сведения об одном контакте. Мы, естественно, будем использовать HTTP GETдля этой функции и будем следовать соглашению, которое мы установили для нашего обычного веб-приложения, и укажем путь /api/v1/contacts/<contact id>. Так, например, если вы хотите просмотреть подробную информацию о контакте с идентификатором 42, вы должны отправить HTTP-запрос GETна адрес /api/v1/contacts/42.

Этот код довольно прост:

@app.route("/api/v1/contacts/<contact_id>", methods=["GET"]) (1)
def json_contacts_view(contact_id=0):
    contact = Contact.find(contact_id) (2)
    return contact.__dict__ (3)

1. Добавьте новый GETмаршрут по пути, который мы хотим использовать для просмотра контактной информации.

2. Найдите контакт по идентификатору, переданному по пути.

3. Преобразуйте контакт в словарь, чтобы его можно было отображать как ответ JSON.

Ничего сложного: ищем контакт по идентификатору, указанному в пути к контроллеру. Затем мы визуализируем его как JSON. Вы должны оценить простоту этого кода!

Далее добавим также обновление и удаление контакта.

Обновление и удаление контактов

Как и в случае с конечной точкой API создания контактов, поскольку для них не существует пользовательского интерфейса HTML, мы можем повторно использовать путь /api/v1/contacts/<contact id>. Мы будем использовать PUTметод HTTP для обновления контакта и DELETE метод для его удаления.

Наш код обновления будет выглядеть почти идентично обработчику создания, за исключением того, что вместо создания нового контакта мы будем искать контакт по идентификатору и обновлять его поля. В этом смысле мы просто объединяем код обработчика создания и обработчика подробного представления.

@app.route("/api/v1/contacts/<contact_id>", methods=["PUT"]) (1)
def json_contacts_edit(contact_id):
    c = Contact.find(contact_id) (2)
    c.update(request.form['first_name'], request.form['last_name'], request.form['phone'], request.form['email']) (3)
    if c.save(): (4)
        return c.__dict__
    else:
        return {"errors": c.errors}, 400

1. Мы обрабатываем PUTзапросы к URL-адресу данного контакта.

2. Найдите контакт по идентификатору, переданному по пути.

3. Обновляем данные контакта из значений, включенных в запрос.

4. Отсюда логика идентична обработчику json_contacts_create().

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

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

@app.route("/api/v1/contacts/<contact_id>", methods=["DELETE"]) (1)
def json_contacts_delete(contact_id=0):
    contact = Contact.find(contact_id)
    contact.delete() (2)
    return jsonify({"success": True}) (3)

1. Мы обрабатываем DELETEзапросы к URL-адресу данного контакта.

2. Найдите контакт и вызовите delete()для него метод.

3. Верните простой объект JSON, указывающий, что контакт был успешно удален.

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

Дополнительные соображения по API данных

Теперь нам нужно было бы сделать гораздо больше, если бы мы хотели сделать этот JSON API готовым к производству. Как минимум нам нужно будет добавить:

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

• Механизм аутентификации. (У нас его тоже нет для нашего веб-приложения!)

• Поддержка нумерации наших контактных данных.

• Несколько мелких вещей, таких как предоставление правильного 404 (Not Found)ответа, если кто-то делает запрос с идентификатором контакта, который не существует.

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

Мы пока оставим авторизацию и рассмотрим только аутентификацию.

Аутентификация в веб-приложениях

В мире веб-приложений HTML аутентификация традиционно выполнялась через страницу входа, на которой у пользователя запрашивается имя пользователя (часто адрес электронной почты) и пароль. Затем этот пароль сверяется с базой данных (хешированных) паролей, чтобы установить, является ли пользователь тем, кем он себя называет. Если пароль верен, создается файл cookie сеанса , указывающий, кто является пользователем. Этот файл cookie затем отправляется с каждым запросом, который пользователь делает к веб-приложению, позволяя приложению узнать, какой пользователь делает данный запрос.

HTTP-файлы cookie

HTTP Cookies — это странная особенность HTTP. В некотором смысле они нарушают цель сохранения состояния без сохранения состояния, основного компонента архитектуры RESTful: сервер часто использует сеансовый файл cookie в качестве индекса состояния, хранящегося на сервере «на стороне», например, в виде кеша последнего действия. выполняется пользователем.

Тем не менее, файлы cookie оказались чрезвычайно полезными, и поэтому люди, как правило, не слишком жалуются на этот их аспект (мы не уверены, какие у нас могут быть другие варианты!) Интересный пример прагматизма, ушедшего (относительно) в веб-разработку.

По сравнению со стандартным подходом к аутентификации веб-приложений, JSON API обычно использует своего рода аутентификацию на основе токена : токен аутентификации будет установлен с помощью такого механизма, как OAuth, и затем этот токен аутентификации будет передан, часто в виде HTTP-заголовка. , с каждым запросом, который делает клиент.

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

• Файлы cookie являются частью спецификации HTTP и могут быть легко установлены HTTP-сервером.

• Токены аутентификации JSON, напротив, часто требуют создания сложной механики обмена, такой как OAuth.

Эти разные механизмы установления аутентификации являются еще одной веской причиной для разделения наших API-интерфейсов JSON и гипермедиа.

«Форма» наших двух API

Когда мы создавали наш API, мы заметили, что во многих случаях JSON API не требует столько конечных точек, сколько наш API гипермедиа: нам не нужен обработчик, например, для предоставления /contacts/newгипермедиа-представления для создания контактов. .

Еще одним аспектом нашего гипермедийного API, который следует учитывать, было улучшение производительности: мы вынесли общее количество контактов на отдельную конечную точку и внедрили шаблон «Отложенная загрузка», чтобы улучшить воспринимаемую производительность нашего приложения.

Теперь, если бы у нас были и гипермедиа, и API JSON, использующие одни и те же пути, захотели бы мы также опубликовать этот API как конечную точку JSON?

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

А что, если каким-то чудом проблемы с производительностью, которые Contact.count()мы решали с помощью шаблона отложенной загрузки, исчезнут? Что ж, в нашем приложении, управляемом гипермедиа, мы можем просто вернуться к старому коду и включить счетчик непосредственно в запрос к /contacts. Мы можем удалить contacts/countконечную точку и всю связанную с ней логику. Благодаря единообразному интерфейсу гипермедиа система продолжит работать нормально.

Но что, если бы мы связали наши API JSON и API гипермедиа вместе и опубликовали их /contacts/countв качестве поддерживаемой конечной точки для нашего API JSON? В этом случае мы не могли просто удалить конечную точку: на нее мог полагаться (не гипермедийный) клиент.

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

Парадигма контроллера представления модели (MVC)

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

Это идеальный контроллер парадигмы Модель-Представление-Контроллер (MVC), которая была так популярна на заре Интернета: контроллер должен быть «тонким», а модель содержать большую часть логики в системе.

Шаблон «Контроллер представления модели»

Шаблон проектирования Model View Controller — это классический архитектурный шаблон в разработке программного обеспечения, оказавший большое влияние на раннюю веб-разработку. Этому больше не придают такого большого значения, поскольку веб-разработка разделилась на фронтенд и бэкенд, но большинство веб-разработчиков все еще знакомы с этой идеей.

Традиционно шаблон MVC отображается в веб-разработке следующим образом:

• Модель — коллекция «доменных» классов, которые реализуют всю логику и правила для конкретного домена, для которого разработано ваше приложение. Модель обычно предоставляет «ресурсы», которые затем представляются клиентам в виде «представлений» HTML.

• Представление. Обычно представления представляют собой своего рода систему шаблонов на стороне клиента и отображают вышеупомянутое HTML-представление для данного экземпляра модели.

• Контроллер. Задача контроллера — принимать HTTP-запросы, преобразовывать их в разумные запросы к модели и перенаправлять эти запросы соответствующим объектам модели. Затем он передает HTML-представление обратно клиенту в качестве ответа HTTP.

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

При правильно построенных «тонких» контроллерах и «толстых» моделях синхронизировать два отдельных API и при этом продолжать развиваться отдельно не так сложно и не так безумно, как может показаться.

HTML-примечания: микроформаты

Микроформаты — это стандарт для внедрения машиночитаемых структурированных данных в HTML. Он использует классы, чтобы пометить определенные элементы как содержащие информацию, подлежащую извлечению, с соглашениями для извлечения общих свойств, таких как имя, URL-адрес и фотография, без классов. Добавляя эти классы в HTML-представление объекта, мы позволяем восстанавливать свойства объекта из HTML. Например, этот простой HTML:

<a class="h-card" href="https://john.example">
  <img src="john.jpg" alt=""> John Doe
</a>

может быть преобразован в эту JSON-подобную структуру с помощью анализатора микроформатов:

{
  "type": ["h-card"],
  "properties": {
    "name": ["John Doe"],
    "photo": ["john.jpg"],
    "url": ["https://john.example"]
  }
}

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

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

Однако микроформаты гораздо проще внедрить. Протокол или стандарт, который требует от веб-сайтов реализации API JSON, имеет высокий технический барьер. Для сравнения, любой веб-сайт можно дополнить микроформатами, просто добавив несколько классов. Другие форматы данных, встроенные в HTML, такие как микроданные и Open Graph, также легко внедрить. Это делает микроформаты полезными для межсайтовых (осмелимся сказать, веб-масштабных ) систем, таких как IndieWeb , которая использует их повсеместно.

---