Якович (1207873), страница 5
Текст из файла (страница 5)
Для получения информации используется метод GET (пер. «получить»), например, GET: http://example.com/api/masters/12 – мы получим информацию о хозяине с id = 12.
Для создания новых записей в базе данных используется метод POST (пер. «отправить»), например, запрос типа POST на URI http://example.com/api/masters/ с набором данных [{«name»: «Иван», «last_name»: «Васильевич»}] добавит нового хозяина с именем и отчеством Иван Васильевич.
При необходимости изменить информацию, можно воспользоваться методом PUT. К примеру, сделав запрос на URI http://example.com/api/masters/12 с набором данных [{«last_name»: «Иванович»}], а затем сделав GET-запрос на тот же URI мы получим обновленные данные у хозяина с id = 12, где «last_name» будет «Иванович».
Для удаления данных используется метод DELETE. При таком запросе на URI http://example.com/api/masters/12 будет удалён хозяин с id = 12.
Стандартизация и документирование
Поскольку REST является архитектурным стилем, для него нет четких стандартов и ограничений, только соглашения и накопленный опыт, ведущий к наиболее эффективному использованию. Это не является недостатком REST, скорее его достоинством: мы можем реализовывать наше API так, как будет наиболее выгодно и удобно с точки зрения технической и использования.
Для оценки качества («зрелости») веб-сервиса была разработана модель на основе анализа сотен веб-сервисов. Она подразделяется на 4 уровня:
– Уровень №1: Один URI – один HTTP метод.
Здесь HTTP используется только для взаимодействия компонентов распределенной системы. Из методов используется только один, например, POST. Как вы уже догадались, такими веб-сервисами являются протоколы XML-RPC и SOAP.
– Уровень 2: Несколько URI, один HTTP метод.
Веб-сервисы этого уровня используют понятие «разделяй и властвуй». Вводится понятие ресурса, и для осуществления действия над конкретным ресурсом используется URL этого ресурса.
Таким образом, если вы хотите выполнить какое-то действие с сущностью, то нужно использовать относительный URL /entity. Если сравнить веб-сервис второго уровня с веб-сервисом первого уровня, то в последнем случае есть только один ресурс, и этот ресурс сам является веб-сервисом.
– Уровень 3: Несколько URI, каждый поддерживает разные HTTP методы (Правильное использование HTTP).
И так, на уровне 2 все сущности веб-сервиса были отделены с помощью ресурсов, но с ресурсом можно выполнять разные действия. Чтобы эти действия тоже были логически разделены, используется возможность HTTP отправлять и принимать запросы разными методами: GET, HEAD, POST, PUT, DELETE, TRACE, CONNECT. Например, для получения данных можно использовать GET, для создания – POST или PUT․
С расширением HTTP с помощью различных методов вводится также необходимость возвращения правильных кодов состояния. Например, на запрос создания сущности, если она создана, должен быть возвращен код 201 (Создан). Если в течении ваших действий кто-то уже добавил идентичную сущность, следует указать код 409 (Конфликт).
– Уровень 4: HATEOAS․ Ресурсы сами описывают свои возможности и взаимосвязи, перекрестные ссылки.
HATEOAS (Hypertext as the Engine of Application State), требование которое очень упрощает работу с веб-сервисом и навигацией по его возможностям. HATEOAS – это способность веб-сервиса указывать в виде URL, действия которые могут быть выполнены с используемым ресурсом.
Преимуществом HATEOAS является то, что оно дает возможность разработчикам веб-сервисов менять URI независимо от клиентов, кроме этого, веб-сервис сам описывает себя.
Однако, есть и негативная сторона: URI могут быть достаточно длинными, а действия над ресурсом могут быть многочисленны, это требует дополнительных вычислительных затрат и занимает ощутимо больший объем.
2 Реализация REST API в системе проектов «Фарпост»
2.1 Цель ВКР
Целью ВКР является проектирование системы с REST архитектурой пригодной для взаимодействия с другими проектами в системе. Разработка такой системы сводится к следующим этапам:
– Постановка задачи
– Выбор инструментов для решения задачи
– Проектирование схемы данных
– Проектирование карты маршрутов
– Разработка
Ключевым этапом при создании приложения с REST архитектурой является грамотная проектировка маршрутов, карта которых будет интуитивно понятна и соответствовать набору сущностей, используемых в проекте. Использование HTTP-методов позволяет не создавать избыточное число маршрутов для каждой операции. Каждая единица маршрута является URI и отвечает за определённые действия.
Например, возьмём одну из базовых сущностей (таблиц базы данных): «Article» (статья). Маршруты будут выглядеть следующим образом:
example.com/api/article/ – подразумевается получение списка статей;
example.com/api/article/5/ – подразумевается получение статьи с id (идентификатором) равным 5.
Данный маршрут не ограничивается одним только получением данных. Действие определяется HTTP-методом запроса. Все примеры выше указаны для метода GET (получить).
Если мы воспользуемся методом POST для 2-го случая, то мы сможем изменить данные определенной статьи.
Если мы воспользуемся методом PUT, то для 1-го случая появится возможность добавить новую статью.
Если DELETE, то в 1-м случае произойдёт удаление конкретной статьи, а для 2-го случая – удаление всех записей таблицы.
Возможно, сущность «Article» связана с другой сущностью, например, «Category» (категория). Тогда, если нам понадобится выбирать статьи, связанные с какой-то конкретной категорией, можно создать следующий маршрут, соответствующий названию категории:
www.example.com/api/articles/{category-name}/
В данном примере в качестве {category-name} (название категории) мы укажем название категории и получим все статьи относящиеся к данной категории. К примеру, можно взять категорию «Science» (наука) и получить URI вида www.example.com/api/articles/science/.
Все задачи в ВКР были выполнены в системе «Фарпост». Были использованы внутренние ресурсы, общая схема взаимодействия указана на рисунке 4. На ней изображены только те ресурсы, которые использовались в работающих проектах.
Серыми линиями изображены взаимодействия между проектами, не используемые для решения поставленных задач. Все проекты взаимодействуют посредством HTTP-запросов. Каждый из проектов независим от другого и в случае падения одного из проектов, остальные проекты не выходят из строя и продолжают работу в штатном режиме.
На рисунке 5 над линиями взаимодействия подписаны краткие названия задач. Проект «Поиск» убран из схемы, так как не участвует в рамках описанных задач.
Рисунок 4 – схема взаимодействия проектов в системе «Фарпост»
Рисунок 5 – схема взаимодействия проектов в системе в рамках поставленных задач
2.2 Разработка API для виджета, отображающего информацию о секции и преподавателе на проекте «Детки»
В рамках производственной задачи необходимо было обеспечить взаимодействие двух проектов в системе: "Детки" и "Секции". На проекте "Детки" требовалось разработать виджет, на котором отображаются несколько случайных секций, случайный преподаватель и информация о них.
Для реализации задачи необходимо было создать API на проекте "Секций", удовлетворяющее требованиям задачи. Суть API заключалась в предоставлении URI, сделав запрос на который будут получены данные для виджета на проекте "Детки".
На этом этапе уже были разработаны методы для получения секций, категорий и преподавателей по следующим маршрутам
– http://api.sections.vl.ru/api/sections
– http://api.sections.vl.ru/api/categories
– http://api.sections.vl.ru/api/trainers
Каждый из URI позволяет получить список сущностей с помощью GET-запроса. Каждый URI отвечает за отдельную сущность, что соответствует идеологии REST.
В силу специфичности задачи и требованию оптимизировать запросы, было решено выделить отдельный URI для поставленной задачи:
– http://api.sections.vl.ru/api/widget
Это позволило получить все необходимые для виджета данные сделав всего один запрос к удалённому серверу -- в конечном итоге это экономит время и интернет-трафик.
Так как разработка ведётся для двух городов: Хабаровска и Владивостока, было принято решение о разделении виджетов через запрос с параметрами:
– http://api.sections.vl.ru/api/widget?city={id},
где {id} – числовой идентификатор города. В соответствии с ним производится выборка из базы данных.
Выборка принимает следующий вид:
– вербальная формулировка: выборка секций, которые относятся к городу {id} и активны
– SQL: SELECT * FROM section WHERE city_id = {id} AND is_active = true;
– На примере реляционной алгебры, по формуле (1):
(1)
«Сделать выборку из таблицы section по условию, что city_id = {id} и секция в рабочем состоянии, а затем сделать проекцию на полученное отношение с целью получить *-аттрибуты».
Поскольку в таблице «section» присутствуют связи по ключу с другими таблицами, например, «category», нам необходимо расширить выборку следующим образом:
– SQL: SELECT * FROM section INNER JOIN sections_categories ON section.id = sections_categories.section_id INNER JOIN category ON category.id = sections_categories.category_id WHERE section.city_id = {id}
– Реляционная алгебра по формулам (2) и (3):
(2) 
. (3)
В результате мы получим работающую секцию для определенного города и связанные с ней категории.
Выбрав необходимые данные, возникает задача формирования ответа. Она нетривиальна. Был выбран ответ в формате JSON (JavaScript Object Notation), который сейчас используется практически везде, также он очень удобен и имеет четко сформулированные стандарты и ограничения. Помимо этого, JSON всецело поддерживается клиентским JavaScript, что делает работу с данными полученными от севера очень простым и удобным.
Для удобства и информативности, ответ формируется следующим образом:
[{
"success" : "true/false"
"data" : { полученные данные из БД }
}]
Таким образом, мы получаем данные в «сыром» виде от проекта «Секции», на рисунке 6 можно увидеть данные:
Рисунок 6 – данные для виджета в формате JSON
Предоставление данных в «универсальных» форматах, типа JSON, даёт нам возможность обмениваться любыми данными не привязываясь к определенной платформе. Мы можем отправить что угодно куда угодно.
Следующим этапом будет интерпретация полученных данных. Для работы с JSON в большинстве языков программирования имеются встроенные или подключаемые функции для работы с данными в этом формате.
В случае проекта «Детки» используется функция json_encode поставляемая языком программирования PHP. В результате получается массив, представляющий собой пары «ключ-значение». На рисунке 7 можно увидеть финальный вариант виджета:
Рисунок 7 – конечное представление виджета на странице сайта
Также, нельзя исключать случая, когда проект «Секции» недоступен по техническим причинам («упал» сервер, какая-то внутренняя ошибка сайта), в этом случае проект «Детки» не может получить данные. Возможны несколько исходов и их обработка.
– Сервер сломан и не отвечает: такая ошибка обрабатывается на стороне проекта «Детки». Выбираются последние полученные данные из кэша;
– Внутренняя ошибка сайта, из-за которой он не может предоставить ответ. В этом случае отдаётся JSON вида:
[{
“success”: “false”,
“message”: “описание ошибки”
}]
2.3 Подготовка API для фотоотчётов на проекте «Детки»
Другой задачей была подготовка API для передачи превью фотоотчётов с проекта «Детки» на «главную Двхаб». В крупные события, например, на 1-е сентября и новый год, на «главную Двхаб» выставляется виджет с превью фотоотчётов с линейки на первое сентября или новогодних утренников.
Для решения этой задачи было разработано API для фотоотчётов на проекте «Детки», которое предоставляет последние фотоотчёты (отсортированные от новых к старым), отфильтрованные по нужной категории и позволяющее выбрать необходимое число фотоотчётов.
Был подготовлен URI http://www.dvhab.ru/detki/photoreports/api/last. Если не указывать никаких параметров в запросе, то API вернёт список последних фотоотчётов, загруженных на проект «Детки».
Для фильтрации по категориям используется параметр «category», принимающий целочисленные значения, соответствующие определенной категории.
Так, например, сделав запрос на URI:
http://www.dvhab.ru/detki/photoreports/api/last?category=1,
![](https://s.studizba.com/z.php?f=/templates/si/i/noavatar.png&w=100&h=100&t=1"){kind=avatar}
