Большинство из нас, разработчиков веб-приложений, в повседневной жизни создают REST API. API — основные средства связи между системами. В этой статье я расскажу, как лучше разрабатывать API, чтобы не совершать типичные ошибки.
Требования Джеффа Безоса: ключ к успеху
Многие из вас уже наверняка знают о требованиях Джеффа Безоса к разработчикам в Amazon. Если вы не слышали об этом, ниже перечислены основные его положения:
- Отныне все группы разработчиков должны раскрывать свои данные и функциональные средства через сервисные интерфейсы;
- Группы разработчиков должны связываться друг с другом с помощью этих интерфейсов;
- Больше никаких форм межпроцессного взаимодействия не допускается: никаких прямых ссылок и считываний данных других групп, никакой модели общей памяти, никаких «лазеек». Единственная разрешенная форма связи осуществляется через служебные интерфейсы по сети;
- Неважно, какую технологию используют разработчики: HTTP, Cobra, Pubsub, встроенные протоколы;
- Больше никаких форм межпроцессного взаимодействия не допускается: никаких прямых ссылок и считываний данных других групп, никакой модели общей памяти, никаких «лазеек». Единственная разрешенная форма связи осуществляется через служебные интерфейсы по сети;
- Больше никаких форм межпроцессного взаимодействия не допускается: никаких прямых ссылок и считываний данных других групп, никакой модели общей памяти, никаких «лазеек». Единственная разрешенная форма связи осуществляется через служебные интерфейсы по сети;
- Все без исключения сервисные интерфейсы с самого начала должны проектироваться выгружаемыми. Это значит, что группа должна планировать интерфейс так, чтобы его можно было раскрыть остальным разработчикам. Исключения не допускаются;
- Все, кто не слушаются этих правил, будут уволены.
В итоге эти требования оказались ключом к успеху Amazon. Компания смогла создавать эластичные системы, а позднее могла предложить эти услуги в лице Amazon Web Services.
Основы Java: создание API для объекта (2021)
Принципы разработки RESTful API
Для разработки RESTful API нужно следовать следующим принципам:
Простота
Нужно убедиться в простоте базового URL для API. Например, если нужно разработать запрос для продуктов, должно получаться так:
/products /products/12345
Первый запрос к API — для всех продуктов, второй — для специфического продукта.
Используйте существительные, а не глаголы
Многие разработчики совершают эту ошибку. Обычно они забывают, что у нас есть HTTP методы для лучшего описания API, и в итоге используют глаголы в URL. Например, запрос для получения всех продуктов звучит так:
/products
/getAllProducts
Так часто поступают при создании URL.
Правильные HTTP методы
В RESTful API существуют различные методы, которые описывают тип операции, которую будет осуществлять API.
REST API — что это? Создаем API с нуля на Express
- GET — для получения ресурса или группы ресурсов;
- POST — для создания ресурса или группы ресурсов;
- PUT/PATCH — для обновления уже существующего ресурса или группы ресурсов;
- DELETE — для удаления уже существующего ресурса или группы ресурсов.
Нужно обязательно убедиться в том, что вы используете верный HTTP метод для каждой операции.
Не забывайте о множественном числе
Эта тема еще стоит под вопросом. Некоторым нравится называть URL ресурсов во множественном числе, некоторым — в единственном. Пример:
/products /product
Мне нравится использовать множественное число, потому что в таком случае не создается путаница: работаем ли мы с одним ресурсом или с группой ресурсов? Также не нужно дополнять базовые URL, например, добавлением all: /product/all .
Кому-то может не нравиться мой подход. Мой единственный совет — делайте так, чтобы в проекте все было единообразно.
Параметры
Иногда нужен API, который должен работать не только по имени. В таком случае для разработки API понадобятся параметры запроса.
нужно использовать /products?name=’ABC’ , а не /getProductsByName ;
нужно использовать /products?type=’xyz’ , а не /getProductsByType .
В таком случае URL не будут слишком длинными, а структура останется простой.
Правильные HTTP коды
Существует множество HTTP кодов. Многие из нас используют только два из них: 200 и 500! Это плохая методика. Ниже перечислены часто используемые HTTP коды:
- 200 OK — самый часто используемый код, свидетельствующий об успехе операции;
- 201 CREATED — используется, когда с помощью метода POST создается ресурс;
- 202 ACCEPTED — используется, чтобы сообщить, что ресурс принят на сервер;
- 400 BAD REQUEST — используется, когда со стороны клиента допущена ошибка в вводе;
- 401 UNAUTHORIZED / 403 FORBIDDEN — используются, если для выполнения операции требуется аутентификация пользователя или системы;
- 404 NOT FOUND — используется, если в системе отсутствуют искомые ресурсы;
- 500 INTERNAL SERVER ERROR — это никогда не используется просто так — в таком случае произошла ошибка в системе;
- 502 BAD GATEWAY — используется, если сервер получил некорректный ответ от предыдущего сервера.
Версии
Версии API — важная вещь. Различные компании используют версии по-разному: кто-то — как даты, кто-то — как параметры запросов. Мне нравится указывать версии до названия ресурса. Пример:
/v1/products /v2/products
Мне также кажется, что стоит избегать использования /v1.2/products , так как это подразумевает, что API часто меняется. К тому же, точки в URL не так легко заметить. Так что чем проще, тем лучше.
Также хорошо бы сохранять совместимость с предыдущими версиями. В таком случае, если вы поменяете версию API, у пользователей будет время, прежде чем перейти на новую версию.
Разбиение на страницы
Обязательно нужно разбивать запрос на страницы, если вы работаете с API, который в качестве ответа может предоставить огромный объем данных. Если сбалансированность нагрузки не обеспечена, пользователь может обрушить сервер.
Всегда нужно иметь в виду, что структура API должна быть полностью защищена, в том числе от неосторожного обращения.
В таком случае стоит использовать limit и offset. Пример: /products?limit=25https://falbar.ru/article/sozdanie-restful-api-poshagovaya-instruktsiya» target=»_blank»]falbar.ru[/mask_link]
Как создать api для программы
Рассмотренного в прошлых темах материала достаточно для создания примитивного приложения. В этой теме попробуем реализовать простейшее приложение Web API в стиле REST. Архитектура REST предполагает применение следующих методов или типов запросов HTTP для взаимодействия с сервером, где каждый тип запроса отвечает за определенное действие:
- GET (получение данных)
- POST (добавление данных)
- PUT (изменение данных)
- DELETE (удаление данных)
Поскольку в приложении ASP.NET Core мы можем легко получить и адрес запроса и тип запроса, то реализовать подобную архитектуру не составит труда.
Создание сервера на ASP.NET Core
Вначале определим веб-приложение на ASP.NET Core, которое и будет собственно представлять Web API:
Разберем в общих чертах этот код. Вначале идет определение данных — список объектов Person, с которыми будут работать клиенты:
var users = new List < new() < Name = «Tom», Age = 37 >, new() < Name = «Bob», Age = 41 >, new() < Name = «Sam», Age = 24 >>;
Стоит обратить внимание, что каждый объект Person имеет свойство Id, которое в качестве значения получает Guid — уникальный идентификатор, например «2e752824-1657-4c7f-844b-6ec2e168e99c».
Для упрошения данные определены в виде обычного списка объектов, но в реальной ситуации обычно подобные данные извлекаются из какой-нибудь базы данных.
В методе app.Run() определяем компонент middleware, который в зависимости от типа запросов (GET/POST/PUT/DELETE) выполняет те или иные действия.
Так, когда приложение получает запрос типа GET по адресу «api/users», то срабатывает следующий код:
if (path == «/api/users» request.Method==»GET») < await GetAllPeople(response); >//. // получение всех пользователей async Task GetAllPeople(HttpResponse response)
Запрос GET предполагает получение объектов, и в данном случае отправляем выше определенный список объектов Person.
Когда клиент обращается к приложению для получения одного объекта по id в запрос типа GET по адресу «api/users/[id]», то срабатывает следующий код:
else if (Regex.IsMatch(path, expressionForGuid) request.Method == «GET») < // получаем id из адреса url string? await GetPerson(id, response); >//. // получение одного пользователя по id async Task GetPerson(string? id, HttpResponse response) < // получаем пользователя по id Person? user = users.FirstOrDefault((u) =>u.Id == id); // если пользователь найден, отправляем его if (user != null) await response.WriteAsJsonAsync(user); // если не найден, отправляем статусный код и сообщение об ошибке else < response.StatusCode = 404; await response.WriteAsJsonAsync(new < message = «Пользователь не найден» >); > >
Чтобы убедиться, что в запрошенном адресе после «/api/users/» указан id, проверяем соответствие адреса регулярному выражению: «^/api/users/w-w-w-w-w$» . Данное выражение проверяет соответствие последнего сегмента адреса значению Guid, который имеет формат xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
В этом случае нам надо найти нужного пользователя по Id в списке и отправить клиенту. Если же пользователь по Id не был найден, то возвращаем статусный код 404 с некоторым сообщением в формате JSON.
При получении запроса DELETE действует аналогичная логика:
else if (Regex.IsMatch(path, expressionForGuid) request.Method == «DELETE») < // получаем id из адреса url string? await DeletePerson(id, response); >//. async Task DeletePerson(string? id, HttpResponse response) < // получаем пользователя по id Person? user = users.FirstOrDefault((u) =>u.Id == id); // если пользователь найден, удаляем его if (user != null) < users.Remove(user); await response.WriteAsJsonAsync(user); >// если не найден, отправляем статусный код и сообщение об ошибке else < response.StatusCode = 404; await response.WriteAsJsonAsync(new < message = «Пользователь не найден» >); > >
Только в данном случае, если пользователь найден в списке, удаляем его из списка и посылаем клиенту.
При получении запроса с методом POST по адресу «/api/users» используем метод request.ReadFromJsonAsync() для извлечения данных из запроса:
else if (path == «/api/users» request.Method == «POST») < await CreatePerson(response, request); >//. async Task CreatePerson(HttpResponse response, HttpRequest request) < try < // получаем данные пользователя var user = await request.ReadFromJsonAsync(); if (user != null) < // устанавливаем id для нового пользователя user.Id = Guid.NewGuid().ToString(); // добавляем пользователя в список users.Add(user); await response.WriteAsJsonAsync(user); >else < throw new Exception(«Некорректные данные»); >> catch (Exception) < response.StatusCode = 400; await response.WriteAsJsonAsync(new < message = «Некорректные данные» >); > >
Поскольку при извлечении данных из запроса может произойти исключение (например, в результате парсинга в JSON), оборачиваем весь код в try..catch . И в случае успешного получения данных устанавливаем у нового объекта свойство Id, добавляем его в список users и отправляем обратно клиенту.
Если приложению приходит PUT-запрос, то также с помощью метода request.ReadFromJsonAsync() получаем отправленные клиентом данные. Если объект найден в списке, то изменяем его данные и отправляем обратно клиенту, иначе отправляем статусный код 404:
else if (path == «/api/users» request.Method == «PUT») < await UpdatePerson(response, request); >//. async Task UpdatePerson(HttpResponse response, HttpRequest request) < try < // получаем данные пользователя Person? userData = await request.ReadFromJsonAsync(); if (userData != null) < // получаем пользователя по id var user = users.FirstOrDefault(u =>u.Id == userData.Id); // если пользователь найден, изменяем его данные и отправляем обратно клиенту if (user != null) < user.Age = userData.Age; user.Name = userData.Name; await response.WriteAsJsonAsync(user); >else < response.StatusCode = 404; await response.WriteAsJsonAsync(new < message = «Пользователь не найден» >); > > else < throw new Exception(«Некорректные данные»); >> catch (Exception) < response.StatusCode = 400; await response.WriteAsJsonAsync(new < message = «Некорректные данные» >); > >
В случае, если запрос идет по другому адресу, то отправляем клиенту веб-страницу index.html , которую мы далее определим:
else < response.ContentType = «text/html; charset=utf-8»; await response.SendFileAsync(«html/index.html»); >
Таким образом, мы определили простейший API. Теперь добавим код клиента.
Определение клиента
Теперь добавим в проект папку html , в которую добавим новый файл index.html
Определим в файле index.html следующим код для взаимодействия с сервером ASP.NET Core:
Основная логика здесь заключена в коде javascript. При загрузке страницы в браузере получаем все объекты из БД с помощью функции getUsers() :
async function getUsers() < // отправляет запрос и получаем ответ const response = await fetch(«/api/users», < method: «GET», headers: < «Accept»: «application/json» >>); // если запрос прошел нормально if (response.ok === true) < // получаем данные const users = await response.json(); const rows = document.querySelector(«tbody»); // добавляем полученные элементы в таблицу users.forEach(user =>rows.append(row(user))); > >
Для добавления строк в таблицу используется функция row() , которая возвращает строку. В этой строке будут определены ссылки для изменения и удаления пользователя.
Ссылка для изменения пользователя с помощью функции getUser() получает с сервера выделенного пользователя:
async function getUser(id) < const response = await fetch(`/api/users/$`, < method: «GET», headers: < «Accept»: «application/json» >>); if (response.ok === true) < const user = await response.json(); document.getElementById(«userId»).value = user.id; document.getElementById(«userName»).value = user.name; document.getElementById(«userAge»).value = user.age; >else < // если произошла ошибка, получаем сообщение об ошибке const error = await response.json(); console.log(error.message); // и выводим его на консоль >>
И выделенный пользователь добавляется в форму над таблицей. Эта же форма применяется и для добавления объекта. С помощью скрытого поля, которое хранит id пользователя, мы можем узнать, какое действие выполняется — добавление или редактирование. Если id не установлен (равен пустой строке), то выполняется функция createUser, которая отправляет данные в POST-запросе:
async function createUser(userName, userAge) < const response = await fetch(«api/users», < method: «POST», headers: < «Accept»: «application/json», «Content-Type»: «application/json» >, body: JSON.stringify(< name: userName, age: parseInt(userAge, 10) >) >); if (response.ok === true) < const user = await response.json(); document.querySelector(«tbody»).append(row(user)); >else < const error = await response.json(); console.log(error.message); >>
Если же ранее пользователь был загружен на форму, и в скрытом поле сохранился его id, то выполняется функция editUser, которая отправляет PUT-запрос:
async function editUser(userId, userName, userAge) < const response = await fetch(«api/users», < method: «PUT», headers: < «Accept»: «application/json», «Content-Type»: «application/json» >, body: JSON.stringify(< id: userId, name: userName, age: parseInt(userAge, 10) >) >); if (response.ok === true) < const user = await response.json(); document.querySelector(`tr[data-rowid=’$’]`).replaceWith(row(user)); > else < const error = await response.json(); console.log(error.message); >>
И функция deleteUser() посылает на сервер запрос типа DELETE на удаление пользователя, и при успешном удалении на сервере удаляет объект по id из списка объектов Person.
Теперь запустим проект, и по умолчанию приложение отправит браузеру веб-страницу index.html , которая загрузит список объектов:
После этого мы сможем выполнять все базовые операции с пользователями — получение, добавление, изменение, удаление. Например, добавим нового пользователя:
Источник: metanit.com
Как создать API с помощью Python и Django
API, Application Programming Interface (программный интерфейс приложения), — очень широкое понятие в бэкенд-разработке. Тот API, который мы рассмотрим сегодня, представляет собой сайт без фронтенд-составляющей. Вместо рендеринга HTML-страниц, бэкенд возвращает данные в JSON формате для использования их в нативных или веб-приложениях. Самое пристальное внимание при написании API (как и при написании вебсайтов) нужно обратить на то, как он будет использоваться. Сегодня мы поговорим о том, как использовать Django для создания API для простого приложения со списком дел.
Нам понадобится несколько инструментов. Для выполнения всех шагов я бы рекомендовал вам, вместе с данной статьей, клонировать вот этот учебный проект из GitHub-репозитория. Также вы должны установить Python 3, Django 2.2, и djangorestframework 3.9 (из репозитория запустите pip install -r requirements.txt для установки библиотек).
Если не все будет понятно с установкой Django, можно воспользоваться официальной документацией. Также вам нужно будет скачать бесплатную версию Postman. Postman – отличный инструмент для разработки и тестирования API, но в этой статье мы воспользуемся лишь его самыми базовыми функциями.
Для начала откройте папку taskmanager , содержащую manage.py , и выполните python manage.py migrate в командной строке, чтобы применить миграции баз данных к дефолтной sqlite базе данных Django. Создайте суперпользователя с помощью python manage.py createsuperuser и не забудьте записать имя пользователя и пароль. Они понадобятся нам позже. Затем выполните python manage.py runserver для взаимодействия с API.
Вы можете работать с API двумя способами: просматривая фронтенд Django REST фреймворка или выполняя http-запросы. Откройте браузер и перейдите к 127.0.0.1:8000 или к localhost через порт 8000, где Django-проекты запускаются по умолчанию. Вы увидите веб-страницу со списком доступных конечных точек API. Это важнейший принцип в RESTful подходе к API-разработке: сам API должен показывать пользователям, что доступно и как это использовать.
Сначала давайте посмотрим на функцию api_index в views.py. Она содержит список конечных точек, которые вы посещаете.
Декоратор — часть синтаксиса, которая позволяет легко определять функции высокого порядка, чтобы добавить функциям представления атрибуты (как классам). Представления на основе функций с декораторами — отличный компромисс между простыми функциями и представлениями на основе классов в Django. Этот декоратор предоставляет четыре информационных элемента: типы запросов, заголовки, параметры и возвращаемое значение каждой функции. Декоратор генерирует заголовок и информацию о методе на основе информации, полученной от других декораторов, прикрепленных к функции, и принимает в качестве входных данных параметры и возвращаемые значения на момент вызова данного декоратора.
Помимо вывода результатов index-запроса, мы также будем использовать наш API для взаимодействия с данными пользователя, так что нам понадобится какой-то способ аутентификации. Если бы это был не просто учебный проект, а что-то посерьезнее, можно было бы реализовать регистрацию пользователей (к тому же, это отличная практика, если вы хотите проверить, насколько вы разобрались с понятиями из этой статьи). Но вместо этого мы просто войдем под учетной записью суперпользователя, которую создали заранее.
Важно отметить, что для того, чтобы идентификация на основе токенов заработала, нужно настроить несколько параметров. Гид по настройке можно найти в файле settings.py учебного проекта.
Чтобы верифицировать пользователя, метод api_signin запрашивает имя пользователя и пароль и использует встроенный в Django метод authenticate . Если предоставленные учетные данные верны, он возвращает токен, позволяющий клиенту получить доступ к защищенным конечным точкам API. Помните о том, что данный токен предоставляет те же права доступа, что и пароль, и поэтому должен надежно храниться в клиентском приложении. Теперь мы наконец можем поработать с Postman. Откройте приложение и используйте его для отправки post-запроса к /signin/, как показано на скриншоте.
Теперь, когда у вас есть токен для вашего пользователя, можно разобраться и с остальными составляющими API. Так что давайте немного отвлечемся и посмотрим на Django-модель, лежащую в основе API.
class Task(models.Model): user = models.ForeignKey(User, on_delete=models.CASCADE) #Каждая задача принадлежит только одному пользователю description = models.CharField(max_length=150) #У каждой задачи есть описание due = models.DateField() #У каждой задачи есть дата выполнения, тип datetime.date
Модель Task представляет собой довольно простой подход к менеджменту задач нашего приложения. Каждый элемент имеет описание, например, «Написать API с помощью Django» и дату выполнения. Задачи также связаны внешним ключом с объектом Django User , что означает, что каждая задача принадлежит только одному конкретному пользователю, но каждый пользователь может иметь неограниченное количество задач или не иметь вовсе. Каждый объект Django также имеет идентификатор, уникальное целое число, которое можно использовать для ссылки на индивидуальные задачи.
Приложения типа этого часто называют CRUD-приложениями, от «Create, Read, Update, Destroy» (Создание, Чтение, Модификация, Удаление), четырех операций, поддерживаемых нашим приложением на объектах Task.
Для начала создадим пустой список задач, связанных с конкретным пользователем. Используйте Postman для создания GET-запроса к /all/, как на скриншоте ниже. Не забудьте добавить токен к заголовкам этого и всех последующих запросов.
class taskSerializer(serializers.ModelSerializer): class Meta: model = Task fields = (‘id’, ‘description’, ‘due’)
Эта простая модель определяет данные для класса Task: идентификатор, описание и дату выполнения. Сериализаторы могут добавлять и исключать поля и данные из модели. Например, вот этот сериализатор не возвращает идентификатор пользователя, т.к. он бесполезен для конечного клиента.
Теперь нам нужно создать задачу. Для этого используем api_new_task . Обычно для создания объекта в базе данных используется PUT-запрос. Обратите внимание, что этот метод, как и два других, не требует предварительной сериализации данных. Вместо этого мы передаем параметры в конструктор объекта класса Task, их же мы затем сохраним в базу данных.
Мы отправляем количество дней для выполнения задачи, так как это гораздо проще, чем пытаться отправить объект Python-класса Date . Затем в API мы сохраняем какую-нибудь дату в далеком будущем. Чтобы увидеть созданный объект, нужно создать запрос к /new/ для создания задачи и повторить запрос к /all/.
Для редактирования только что созданной задачи нужно создать POST-запрос к api_update_task через /update/. Мы включаем task_id для ссылки на правильную задачу из пользовательского task_set . Код здесь будет немного сложнее, т.к. мы хотим иметь возможность обновлять описания и/ или дату выполнения задачи.
Используйте DELETE-запрос к api_delete_task через /delete/ для удаления задачи. Этот метод работает аналогично функции api_update_task , за исключением того, что вместо изменения задачи он удаляет ее.
Сегодня мы с вами разобрались, как реализовать index-запрос, аутентификацию на основе токенов и четыре основных HTTP-метода для Django API. Вы можете использовать эти знания для поддержки любых веб- и нативных мобильных приложений или для разработки публичного API для обмена данными. Не стесняйтесь клонировать учебный проект, содержащий весь код, представленный в этой статье, и попробуйте реализовать такие расширения как пагинация, ограничение числа запросов и создание пользователя.
Источник: mkdev.me