Как запустить api приложения

Что такое API и как он работает

Простыми словами объясняем, как программы общаются между собой, и практикуем API-вызовы.

Иллюстрация: Катя Павловская для Skillbox Media

Евгений Кучерявый

Пишет о программировании, в свободное время создаёт игры. Мечтает открыть свою студию и выпускать ламповые RPG.

Заходите вы на сайт с вакансиями и ищете работу бэкенд-разработчиком, а там почти в каждой вакансии написано, что нужно уметь работать с REST API, или SOAP API, или просто API. Что всё это значит и зачем нужно программисту? Давайте разбираться.

Что такое API

API (англ. Application Programming Interface — программный интерфейс приложения) — это набор способов и правил, по которым различные программы общаются между собой и обмениваются данными.

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

Допустим, вы покупаете билет в кино с помощью банковской карты. Во время покупки терминал обращается к API банка, который выпустил вашу карту, и отправляет запрос на оплату. А если вы заказываете такси через приложение, оно обращается к платёжной системе тоже через API.

Программный интерфейс похож на договор между клиентом и продавцом. Только клиентом выступает приложение, которому нужны данные, а продавцом — сервер или ресурс, с которого мы эти данные берём. В таком договоре прописываются условия того, как и какие данные может получить клиент.

API встречается практически везде:

• В языках программирования он помогает функциям корректно общаться друг с другом. Вызывающая функция должна соблюдать тип данных и последовательность параметров вызываемой функции.
• В операционной системе он помогает программам получать данные из памяти или менять настройки ОС. Поэтому, чтобы разрабатывать приложения под конкретную операционную систему, нужно знать её API.
• В вебе сервисы общаются друг с другом через программный интерфейс. Если API открытый, то официальную документацию по работе с ним публикуют создатели сервиса-источника. Так, например, выглядит документация Telegram.

Несмотря на то что термин довольно широкий, чаще всего в вакансиях речь идёт именно о третьем варианте.

Почему API называют интерфейсом

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

С помощью интерфейса можно использовать возможности разных систем, не задумываясь о том, как они обрабатывают наши запросы и что у них «под капотом». Например, чтобы позвонить, не обязательно знать, как смартфон обрабатывает нажатия на тачскрин. Важно лишь, что в гаджете есть «кнопка», которая всегда возвращает одинаковый результат в ответ на определённые действия.

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

Как API помогает писать надёжные программы

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

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

• работать с файловой системой;
• отрисовывать графику;
• хранить данные;
• использовать сетевые возможности;
• воспроизводить аудио и так далее.

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

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

Почему API так популярны у программистов

Программные интерфейсы сервисов и библиотек позволяют разработчикам не изобретать велосипеды. Зачем писать код, когда можно воспользоваться готовым?

Вот какие возможности даёт API:

• Предоставляет доступ к готовым инструментам. Например, к функциям библиотеки для машинного обучения TensorFlow — они помогают быстро создать нейросеть, не тратя время на разработку инструментов с нуля.
• Повышает безопасность. API позволяет вынести в отдельное приложение функциональность, которая должна быть защищена. Так снижается вероятность некорректного использования этих функций другими программами.
• Связывает разные системы. Если вам нужно подключить к сайту платёжную систему или авторизацию через соцсети, без API не обойтись.
• Снижает стоимость разработки. Часто бывает, что дешевле воспользоваться платным API, чем создавать функциональность с нуля.

Стороннее API обычно безопасное, потому что над ним работает коммерческая организация или целое сообщество разработчиков. И конечно, с его помощью даже работа над сложными проектами становится проще и приятнее.

Какие функций могут входить в API

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

Например, в API для анализа текстов будут функции поиска всех однокоренных слов, подсчёта количества союзов и выявления часто встречающихся словосочетаний.

Функции API могут решать не только утилитарные задачи конкретных приложений. Это может стать элементом маркетинга, когда доступ к API предлагается как отдельная услуга.

Как компании зарабатывают с помощью API

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

Например, «Яндекс» предоставляет платные API таких технологий:

• переводчика с машинным обучением;
• системы распознавания и синтеза речи;
• платформы облачных вычислений и так далее.

Популярные социальные сети тоже предоставляют доступ к своим API. Через них можно, например, создать игру для «ВКонтакте» или добавить на сайт авторизацию через Google.

При этом компании обычно не раскрывают принципы реализации своих интерфейсов, поэтому для программистов они остаются «чёрными ящиками».

Как происходит вызов функций API

Мы уже столько говорим об API, но так и не показали, как с ним работать. На самом деле здесь нет ничего сложного. Как вызывать функции конкретного API — описывается в документации, а принципы работы примерно одни и те же.

Вот пример вызова методов библиотек в языке Python:

# Подключаем библиотеку import numpy as np # Вызываем метод, который возвращает модуль числа -5 x = np.abs(-5) # Выводим переменную x print(x)

Если API предоставляет функции через интернет (Web API), нужно отправить на сервер HTTP-запрос с данными в формате JSON. Пример синтеза речи с помощью API Yandex.SpeechKit:

import requests import json # Помещаем в переменную API_URL адрес API API_URL = "https://tts.api.cloud.yandex.net/speech/v1/tts:synthesize" # Помещаем в словарь data данные для отправки в API Yandex.SpeechKit data = < "text": "Привет! Это пример кода для статьи про API в Skillbox Media", "lang": "ru-RU", "speed": 1, "voice": "filipp", "emotion": "good" > # Преобразуем данные в строку в формате JSON json_str = json.dumps(data) # Отправляем данные на сервер и получаем ответ answer = requests.post(API_URL, json_str)

Можете запустить этот код и послушать результат.

Также бывают косвенные вызовы API — когда вызов происходит при участии посредника (другой функции или другого API). Например, когда пользователь нажимает кнопку «Обновить», он тоже взаимодействует с API браузера, но делает это не напрямую, а через графический интерфейс.

Что запомнить

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

API экономит время программистов и уменьшает расходы бизнеса на разработку.

Читайте также:

• 9 софт-скиллов идеального джуна: взгляд тимлида
• Все любят язык Go: почему он стал популярным и сколько зарабатывают разработчики
• Что такое тестирование программ и зачем оно нужно

API для начинающих: Как использовать API? Полное руководство

API (App Programming Interface) — это интерфейсная программа, которая помогает взаимодействовать с другим программным обеспечением подобно пользовательскому интерфейсу (UI). Он является основной точкой входа для веб-сайта и приложения, включая интеграцию со сторонними разработчиками, облегчая жизнь разработчикам. Эта статья предназначена для тех, кто собирается использовать API в своих проектах. Давайте посмотрим, что такое API?

API предоставляют приложениям возможность взаимодействовать друг с другом. Например, одно приложение может запросить данные у другого приложения и получить их в ответ. Компонент API (Application Program Interface) может разрешать функции одного приложения, а второе приложение может их использовать. Консорциум Всемирной паутины (W3C) определяет API как «набор определений подпрограмм, протоколов и сервисов для создания программных приложений».

Как научиться интеграции API?

API используются в самых разных приложениях, от небольших проектов, например, школьных, до масштабных глобальных сервисов, таких как Google Maps или Facebook. Например, знаменитая кнопка Tweet в Twitter — это API-сервис, который исполняемый код может вызвать и отправить твит от имени пользователя (хотя в последних версиях это изменилось, и большая часть функциональности стала частью страницы).

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

W3C имеет точку входа в API, где вы можете найти ссылки на инструменты, ресурсы, примеры и многие другие ценные вещи. Если вы работаете под Windows или Linux, у W3C есть онлайн-инструмент для документирования служб API, который позволяет тестировать API. Есть также инструменты на базе HTML5 и приложения, удобные для мобильных устройств. Помимо W3C, несколько хороших ресурсов есть у Google:

Google предоставляет множество API для доступа к информации из своих служб. Одним из таких API является API Google Maps. Этот инструмент — отличный способ узнать об API, поскольку в нем используются HTML и JavaScript, которые должны быть знакомы каждому, кто разрабатывает веб-приложение для бизнеса.

Различные этапы изучения интеграции API включают в себя:

• Понять, что делают API
• Разберитесь в различных типах API
• Узнайте об API W3C и Google API
• Определите доступные сервисы, к которым можно получить доступ с помощью API
• Интегрировать API для создания рабочей системы или программы с вашим кодом и протестировать API
• Изучить и понять инструменты, язык сценариев, языки программирования, фреймворки и стиль проектирования для интеграции вашей системы с существующей посредством интеграции API
• Попробуйте реализовать коллекции, необходимые для взаимодействия с сервисом, реализованным через API, и научитесь тестировать коллекции API в своем коде, например, объектную модель JSON или модель AObject и т.д.

Как создать API?

Существует несколько способов создания API. Один из самых простых — использовать онлайн-сервис. Многие онлайн-сервисы позволяют разрабатывать и тестировать интерфейс программирования приложений бесплатно или за небольшую плату. Одним из таких примеров является no-code AppMaster, отличная и очень надежная платформа для создания и реализации API. Спецификация является неотъемлемой частью создания API при его проектировании и документировании. Спецификация расскажет другим разработчикам, как использовать ваш API и что им нужно сделать, чтобы взаимодействовать с ним.

Что мне нужно для начала работы?

Для начала работы с тестовым API вам понадобится несколько предметов:

• Доменное имя
• Место для размещения кода, например, GitHub или SourceForge
• HTTP-сервер, чтобы вы могли запускать свой код локально

На каком языке должен быть написан мой API?

Не существует правил для создания ключа API. Это зависит от ваших потребностей, но некоторые распространенные варианты включают:

В чем преимущество создания API?

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

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

API эндпоинты

API эндпоинты — это методы которые представляют собой некий шлюз, который соединяет серверные приложения со встроенным интерфейсом. Простыми словами, это адрес, на который отправляются сообщения. Эти методы могут включать JSON, XML и другие. Каждый URL должен иметь метод, который запрашивается, например GET или POST.

Попробуйте no-code платформу AppMaster

AppMaster поможет создать любое веб, мобильное или серверное приложение в 10 раз быстрее и 3 раза дешевле

Использование API эндпоинтов

API эндпоинты- это цифровое место, где API получает запрос ресурса. Таким образом, конечная точка — это, по сути, URL (Uniform Resource Locator), который предоставляет информацию о ресурсе. Ниже перечислены некоторые важные моменты, касающиеся характеристик API эндпоинтов.

• Определите и используйте имя URL эндпоинта
• Определите и используйте метод HTTP
• Определите тело запроса и его параметры
• Определите стратегию аутентификации, если необходимо
• Для удобства к каждому эндпоинту прикрепляется дополнительный параметр. Точно так же, как при создании функции в других языках программирования, вы должны включить эндпоинты или эти эндпоинты в свой исходный код, поэтому обязательно объявите свои эндпоинты или эти эндпоинты в заголовочном файле в верхней части вашего исходного кода.

Что такое API эндпоинт?

• Эндпоинт — это компонент API
• Эндпоинт — это местоположение ресурса
• API извлекает ресурсы с помощью URL эндпоинта
• Эндпоинт является одним из концов канала связи

Что такое API для начинающих?

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

Пользователи могут использовать API для получения информации от других программ, получения данных и многого другого. Например, в мире iPhone вы можете использовать API, доступный в вашем приложении, для получения данных от другого приложения, например, созданного Facebook, Twitter и т.д., через App Store компании Apple.

Ниже перечислены некоторые из различных типов API:

API на основе XML

Они также известны как API веб-служб и REST API (передача репрезентативного состояния). Единственное различие между API на основе XML и API веб-служб заключается в их синтаксисе. API на основе XML поддерживают все основные веб-браузеры, включая Internet Explorer, Safari, Chrome и Firefox на Windows, OSX и Linux; Internet Explorer 9+ на Windows Phone и другие веб-браузеры. — RESTful API: Это разновидность современного API. Он использует меньшую пропускную способность, чем другие форматы, такие как SOAP. NET.

SOAP APIs

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

• Удаленные вызовы процедур (RPC)
• Удаленные вызовы процедур используют SOAP поверх HTTP для связи между клиентом и сервером в API-ключе. Это относительно новый способ создания API. Он включает удаленные конечные точки для клиента, чтобы отправлять и получать данные и передавать команды.
• Обобщенный язык объектного моделирования (GOML): Это более новый формат для создания API, который не сохраняет детали от предыдущих запросов. Вместо этого метод называется функцией в других языках программирования. Единственный недостаток — в нем нет системы событий, но Apple использовала его для создания «swoosh» в iPhone и службы приложений Camera.

Интеграция с API

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

Прежде чем начать интегрировать API-ключ в свой проект, необходимо сделать две вещи:

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

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

При проектировании вашей системы необходимо продумать, какая информация требуется и какие отношения существуют между ними.

Ниже приведены несколько примеров:

• Создайте онлайн-систему, которая отслеживает содержимое веб-сайта.
• На сайте есть несколько статей с названиями и авторами (набор данных).
• На сайте есть миниатюры для каждой статьи (набор данных).
• Пользователь выбирает статью на главной странице (команда).

Команда проходит через вашу программу и запрашивает конкретную статью из базы данных.

Легко ли освоить API?

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

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

Конечные точки API (эндпоинты) — это важные и ценные методы при интеграции API в проект. При разработке ключа API необходимо продумать различные методы, такие как создание, чтение, обновление и удаление (CRUD), а также параметры. Вы должны описать все эти параметры до начала работы над проектом. Ниже перечислены различные методы, которые вы можете использовать для взаимодействия с конечными точками API (эндпоинтами):

Попробуйте no-code платформу AppMaster

AppMaster поможет создать любое веб, мобильное или серверное приложение в 10 раз быстрее и 3 раза дешевле

GET

Этот метод используется для получения данных из URL. Он также используется для получения полного содержимого HTML-страницы в API. Например, если вы хотите получить всю информацию об определенном пользователе в API, вы запросите его профиль на сервере. Затем сервер отправит ответ.

POST

Если вы хотите отправить данные на сервер и сохранить их, то этот метод — то, что вам нужно. Он используется для создания новой записи в вашем API. Для этого укажите тип запроса в вашем API (например, запись в блоге).

PUT

Этот метод используется для обновления данных в базе данных. В API, если вы хотите изменить информацию в определенной базе данных, вы будете использовать этот метод. Сервер отправит уведомление об успешном обновлении данных.

DELETE

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

Могу ли я создать свой API?

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

Создание пользовательского типа данных или фильтра также возможно, но не обязательно. Если вы хотите работать с уникальным типом данных или функциональностью фильтра, то вам нужен Identity Provider, который будет предоставлять эту функциональность для ваших клиентов при тестировании API (Application Program Interface).

Обучение отнимает много времени, и без соответствующих инструкций или объяснений потребуется время, чтобы понять предмет. Это точно применимо к разработке API; следовательно, лучше проверить, как другие разработчики разработали свои API. Как только вы ознакомитесь с предметом, то с помощью AppMaster вы сможете приступить к созданию своего приложения прикладного программного интерфейса (API) для вашего проекта. Если вы хотите использовать существующий ключ API, то действуйте. Но если вы хотите создать свой собственный и привести его в соответствие со временем, попробуйте использовать AppMaster для разработки приложения для вашего бизнеса.

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

Существует множество преимуществ, которые мы можем получить от разработки API-ключа. Начнем с того, что ваше приложение станет более привлекательным для ваших пользователей, поскольку оно сможет предоставлять информацию о ресурсах. Кроме того, вы сможете лучше управлять своими данными, потому что приложение может легко получить к ним доступ в любом месте. Вопросы безопасности, связанные с тестированием API (Application Program Interface), также решаются благодаря отсутствию необходимости передавать конфиденциальные данные по сети. Это гарантирует, что никто не получит доступ к тестовому API (Application Program Interface), что впоследствии может привести к проблемам.

Заключительные мысли

API могут быть очень полезны для вашего бизнеса, поскольку они отправляют и получают данные из облака и выступают в качестве ключа. Тестировать API (Application Program Interface) очень удобно, поэтому вы можете с легкостью использовать их для создания приложения. Кроме того, нет необходимости в том, чтобы ваш сервис мобильных приложений соединялся с вашим бэк-эндом, поскольку API (Application Program Interface) сделает это за вас. Если вы хотите создать приложение, собирающее данные, начните изучать возможности разработки и тестирования API (Application Program Interface), предлагаемые AppMaster. AppMaster — это платформа, призванная помочь компаниям создать свой API за несколько минут без какого-либо опыта. Цель платформы — упростить процесс создания и тестирования API в кратчайшие сроки.

Платформа предоставляет все ключевые функциональные возможности для тестирования API и разработки исполнения API. После создания API (прикладного программного интерфейса) вы можете использовать его в качестве отправной точки для создания своих приложений. После этого вы сможете продвигать свои услуги и получать больше клиентов. Посетите AppMaster для получения дополнительной информации о no-code приложениях и разработке API.

Пишем API на Python (с Flask и RapidAPI)

Если вы читаете эту статью, вероятно, вы уже знакомы с возможностями, которые открываются при использовании API (Application Programming Interface).

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

Ответ прост: нужно создать собственный API.

Несмотря на то, что это поначалу кажется сложной задачей, на самом деле всё просто. Мы расскажем, как это сделать с помощью Python.

Что нужно для начала работы

Для разработки API необходимы:

• Python 3;
• Flask — простой и легкий в использовании фреймворк для создания веб-приложений;
• Flask-RESTful — расширение для Flask, которое позволяет разработать REST API быстро и с минимальной настройкой.

pip install flask-restful

Рекомендуем бесплатный интенсив по программированию для начинающих:
Разработка telegram-бота на C# — 26–28 августа. Бесплатный интенсив, который позволяет разобраться в том, как работают боты-помощники, в особенностях работы с API Telegram и прочих нюансах. Трое лучших участников получат от Skillbox 30 000 рублей.

Перед тем как начать

Мы собираемся разработать RESTful API с базовой CRUID-функциональностью.

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

Что такое REST?

REST API (Representational State Transfer) — это API, которое использует HTTP-запросы для обмена данными.

REST API должны соответствовать определенным критериям:

• Архитектура клиент-сервер: клиент взаимодействует с пользовательским интерфейсом, а сервер — с бэкендом и хранилищем данных. Клиент и сервер независимы, любой из них может быть заменен отдельно от другого.
• Stateless — никакие клиентские данные не сохраняются на сервере. Состояние сеанса хранится на стороне клиента.
• Кэшируемость — клиенты могут кэшировать ответы сервера для улучшения общей производительности.

CRUD — концепция программирования, которая описывает четыре базовых действия (create, read, update и delete).

В REST API типы запросов и методы запроса отвечают за такие действия, как post, get, put, delete.

Теперь, когда мы разобрались с базовыми терминами, можно приступить к созданию API.

Разработка

Давайте создадим репозиторий цитат об искусственном интеллекте. ИИ — одна из наиболее активно развивающихся технологий сегодня, а Python — популярный инструмент для работы с ИИ.

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

Начнем с импорта необходимых модулей и настройки Flask:

from flask import Flask from flask_restful import Api, Resource, reqparse import random app = Flask(__name__) api = Api(app)

В этом сниппете Flask, Api и Resource — классы, которые нам нужны.

Reqparse — это интерфейс парсинга запросов Flask-RESTful… Также понадобится модуль random для отображения случайной цитаты.

Теперь мы создадим репозиторий цитат об ИИ.

Каждая запись репо будет содержать:

• цифровой ID;
• имя автора цитаты;
• цитату.

ai_quotes = [ < "id": 0, "author": "Kevin Kelly", "quote": "The business plans of the next 10,000 startups are easy to forecast: " + "Take X and add AI." >, < "id": 1, "author": "Stephen Hawking", "quote": "The development of full artificial intelligence could " + "spell the end of the human race… " + "It would take off on its own, and re-design " + "itself at an ever increasing rate. " + "Humans, who are limited by slow biological evolution, " + "couldn't compete, and would be superseded." >, < "id": 2, "author": "Claude Shannon", "quote": "I visualize a time when we will be to robots what " + "dogs are to humans, " + "and I’m rooting for the machines." >, < "id": 3, "author": "Elon Musk", "quote": "The pace of progress in artificial intelligence " + "(I’m not referring to narrow AI) " + "is incredibly fast. Unless you have direct " + "exposure to groups like Deepmind, " + "you have no idea how fast — it is growing " + "at a pace close to exponential. " + "The risk of something seriously dangerous " + "happening is in the five-year timeframe." + "10 years at most." >, < "id": 4, "author": "Geoffrey Hinton", "quote": "I have always been convinced that the only way " + "to get artificial intelligence to work " + "is to do the computation in a way similar to the human brain. " + "That is the goal I have been pursuing. We are making progress, " + "though we still have lots to learn about " + "how the brain actually works." >, < "id": 5, "author": "Pedro Domingos", "quote": "People worry that computers will " + "get too smart and take over the world, " + "but the real problem is that they're too stupid " + "and they've already taken over the world." >, < "id": 6, "author": "Alan Turing", "quote": "It seems probable that once the machine thinking " + "method had started, it would not take long " + "to outstrip our feeble powers… " + "They would be able to converse " + "with each other to sharpen their wits. " + "At some stage therefore, we should " + "have to expect the machines to take control." >, < "id": 7, "author": "Ray Kurzweil", "quote": "Artificial intelligence will reach " + "human levels by around 2029. " + "Follow that out further to, say, 2045, " + "we will have multiplied the intelligence, " + "the human biological machine intelligence " + "of our civilization a billion-fold." >, < "id": 8, "author": "Sebastian Thrun", "quote": "Nobody phrases it this way, but I think " + "that artificial intelligence " + "is almost a humanities discipline. It's really an attempt " + "to understand human intelligence and human cognition." >, < "id": 9, "author": "Andrew Ng", "quote": "We're making this analogy that AI is the new electricity." + "Electricity transformed industries: agriculture, " + "transportation, communication, manufacturing." >]

Теперь нужно создать ресурсный класс Quote, который будет определять операции эндпоинтов нашего API. Внутри класса нужно заявить четыре метода: get, post, put, delete.

Начнем с метода GET

Он дает возможность получить определенную цитату путем указания ее ID или же случайную цитату, если ID не указан.

class Quote(Resource): def get(self, if 0: return random.choice(ai_quotes), 200 for quote in ai_quotes: if(quote["id"] == id): return quote, 200 return "Quote not found", 404

Метод GET возвращает случайную цитату, если ID содержит дефолтное значение, т.е. при вызове метода ID не был задан.

Если он задан, то метод ищет среди цитат и находит ту, которая содержит заданный ID. Если же ничего не найдено, выводится сообщение “Quote not found, 404”.

Помните: метод возвращает HTTP-статус 200 в случае успешного запроса и 404, если запись не найдена.

Теперь давайте создадим POST-метод для добавления новой цитаты в репозиторий

Он будет получать идентификатор каждой новой цитаты при вводе. Кроме того, POST будет использовать reqparse для парсинга параметров, которые будут идти в теле запроса (автор и текст цитаты).

def post(self, id): parser = reqparse.RequestParser() parser.add_argument("author") parser.add_argument("quote") params = parser.parse_args() for quote in ai_quotes: if(id == quote["id"]): return f"Quote with id already exists", 400 quote = < "id": int(id), "author": params["author"], "quote": params["quote"] >ai_quotes.append(quote) return quote, 201

В коде выше POST-метод принял ID цитаты. Затем, используя reqparse, он получил автора и цитату из запроса, сохранив их в словаре params.

Если цитата с указанным ID уже существует, то метод выводит соответствующее сообщение и код 400.

Если цитата с указанным ID еще не была создана, метод создает новую запись с указанным ID и автором, а также другими параметрами. Затем он добавляет запись в список ai_quotes и возвращает запись с новой цитатой вместе с кодом 201.

Теперь создаем PUT-метод для изменения существующей цитаты в репозитории

def put(self, id): parser = reqparse.RequestParser() parser.add_argument("author") parser.add_argument("quote") params = parser.parse_args() for quote in ai_quotes: if(id == quote["id"]): quote["author"] = params["author"] quote["quote"] = params["quote"] return quote, 200 quote = < "id": id, "author": params["author"], "quote": params["quote"] >ai_quotes.append(quote) return quote, 201

PUT-метод, аналогично предыдущему примеру, берет ID и input и парсит параметры цитаты, используя reqparse.

Если цитата с указанным ID существует, метод обновит ее с новыми параметрами, а затем выведет обновленную цитату с кодом 200. Если цитаты с указанным ID еще нет, будет создана новая запись с кодом 201.

Наконец, давайте создадим DELETE-метод для удаления цитаты, которая уже не вдохновляет

def delete(self, id): global ai_quotes ai_quotes = [qoute for qoute in ai_quotes if qoute["id"] != id] return f"Quote with id is deleted.", 200

Этот метод получает ID цитаты при вводе и обновляет список ai_quotes, используя общий список.

Теперь, когда мы создали все методы, всё, что нам нужно, — просто добавить resource к API, задать путь и запустить Flask.

api.add_resource(Quote, "/ai-quotes", "/ai-quotes/", "/ai-quotes/") if __name__ == '__main__': app.run(debug=True)

Наш REST API Service готов!

Далее мы можем сохранить код в файл app.py, запустив его в консоли при помощи команды:

python3 app.py

Если все хорошо, то мы получим нечто вроде этого:

* Debug mode: on
* Running on 127.0.0.1:5000/ (Press CTRL+C to quit)
* Restarting with stat
* Debugger is active!
* Debugger PIN: XXXXXXX

Тестируем API

После того как API создан, его нужно протестировать.

Сделать это можно при помощи консольной утилиты curl или клиента Insomnia REST либо же опубликовав API на Rapid API.

Публикуем наш API

RapidAPI — самый большой в мире маркетплейс с более чем 10 000 API (и около 1 млн разработчиков).

RapidAPI не только предоставляет единый интерфейс для работы со сторонними API, но и даtт возможность быстро и без проблем опубликовать ваш собственный API.

Для того чтобы сделать это, сначала нужно опубликовать его на каком-нибудь сервере в сети. В нашем случае воспользуемся Heroku. Работа с ним не должна вызвать никаких сложностей, (узнать о нём больше можно здесь).

Как опубликовать ваш API на Heroku

1. Устанавливаем Heroku.

Первым делом нужно зарегистрироваться и установить Heroku Command Line Interface (CLI). Это работает на Ubuntu 16+.

sudo snap install heroku —classic

heroku login

2. Добавляем необходимые файлы.

Теперь нужно добавить файлы для публикации в папку в нашем приложении:

• requirements.txt со списком необходимых Python модулей;
• Procfile, который указывает, какие команды должны быть выполнены для запуска приложения;
• .gitignore — для исключения файлов, которые не нужны на сервере.

• flask
• flask-restful
• gunicorn

Procfile будет содержать:

web: gunicorn app:app

*.pyc __pycache__/

Теперь, когда созданы файлы, давайте инициализируем git-репо и закоммитим:

git init git add git commit -m "First API commit"

3. Создаем новое Heroku-приложение.

heroku create

Отправляем master branch в удаленный репо Heroku:

git push heroku master

Теперь можно начать, открыв API Service при помощи команд:

heroku ps:scale web=1 heroku open 

Как добавить ваш Python API в маркетплейс RapidAPI

После того как API-сервис опубликован на Heroku, можно добавить его к Rapid API. Здесь подробная документация по этой теме.

1. Создаем аккаунт RapidAPI.

Регистрируем бесплатную учетную запись — это можно сделать при помощи Facebook, Google, GitHub.

2. Добавляем API в панель управления.

3. Далее вводим общую информацию о своем API.

4. После нажатия “Add API” появляется новая страничка, где можно ввести информацию о нашем API.

5. Теперь можно либо вручную ввести эндпоинты API, либо загрузить swagger-file при помощи OpenAPI.

Ну а теперь нужно задать эндпоинты нашего API на странице Endpoints. В нашем случае эндпоинты соответствуют концепции CRUD (get, post, put, delete).

Далее нужно создать эндпоинт GET AI Quote, который выводит случайную цитату (в том случае, если ID дефолтный) или цитату для указанного ID.

Для создания эндпоинта нужно нажать кнопку “Create Endpoint”.

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

Если все хорошо, страничка API будет выглядеть как-то так:

Заключение

В этой статье мы изучили процесс создания собственного RESTful API Service на Python, вместе с процессом публикации API в облаке Heroku и добавлением его в каталог RapidAPI.

Но в тестовом варианте были показаны только базовые принципы разработки API — такие нюансы, как безопасность, отказоустойчивость и масштабируемость, не рассматривались.

При разработке реального API все это нужно учитывать.

• Блог компании Skillbox
• Python
• Программирование
• API
• Учебный процесс в IT

Как написать удобный API — 10 рекомендаций

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

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

1. Не используйте глаголы в URL *

* — если это одна из CRUD-операций.

За действие с ресурсом отвечают CRUD-методы запроса: POST — создать (create), GET — получить (read), PUT/PATH — обновить (update), DELETE — удалить (ну вы поняли). Плохо:

POST /users//delete - удаление пользователя POST /bookings//update - обновление бронировки

Хорошо:

DELETE /users/ PUT /bookings/

2. Используйте глаголы в URL

Плохо:

POST /users//books//create - добавить книгу пользователю

Хорошо:

POST /users//books//attach POST /users//notifications/send - отправить уведомление пользователю

3. Выделяйте новые сущности

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

POST /wishlist//

4. Используйте один идентификатор ресурса *

* — если ваша структура данных это позволяет.

Это значит если у вас есть записи вида один ко многим, например
бронь -> путешественники (booking->travellers), вам будет достаточно передавать в запросе идентификатор путешественника.

Плохо:

# получение данных путешественника GET /bookings//travellers/

Хорошо:

GET /bookings/travellers/

Также замечу, что /bookings/travellers/ лучше, чем просто /travellers . Хорошо придерживаться иерархии данных в своем API.

5. Все ресурсы во множественном числе

Плохо:

GET /user/ - получение данных пользователя POST /ticket//book - бронирование билета

Хорошо:

GET /users/ POST /tickets//book

6. Используйте HTTP-статусы по максимуму

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

• 400 Bad Request — клиент отправил неверный запрос, например, отсутствует обязательный параметр запроса.
• 401 Unauthorized — клиенту не удалось пройти обязательную аутентификацию на сервере для обработки запроса.
• 403 Forbidden — клиент аутентифицирован, но не имеет разрешения на доступ к запрошенному ресурсу.
• 404 Not Found — запрошенный ресурс не существует.
• 409 Conflict — этот ответ отправляется, когда запрос конфликтует с текущим состоянием сервера.
• 500 Internal Server Error — на сервере произошла общая ошибка.
• 503 Service Unavailable — запрошенная услуга недоступна.

7. Модификаторы получения ресурса

Логика построения роутов может быть не связана с архитектурой проекта или структурой базы данных. Например, в бд есть викторины и пройденные викторины — две отдельные таблицы (quizzes и passed_quizzes). Но для апи это могут быть просто викторины, а пройденные викторины это модификатор.

Пример: /quizzes и /quizzes/passed . Здесь quizzes — ресурс (викторины), passed — модификатор (пройденные).

Плохо:

GET /passed-quizzes - получение пройденных викторин GET /booked-tickets - получение забронированных билетов POST /gold-users - создание премиум пользователя

Хорошо:

GET /tickets/booked POST /users/gold

8. Выберите одну структуру ответов

Когда на два запроса к API может быть получен совсем разный по структуре ответ — это грустно. Старайтесь сформировать одну четкую структуру, которой всегда будете придерживаться. Будет круто еще включить служебные поля, несущие дополнительную информацию.

Плохо:

GET /book/

Хорошо:

GET /book/  < "status": 0, "message": "ok", "data": >

В этом примере 3 поля универсальны и могут использоваться для любого ответа от апи. status , message — собственный статус и сообщение приложения по которому клиент сможет ориентироваться, эти поля сообщат ему дополнительную информацию о процессе обработки запроса, но не данные ресурса. Например, в нашем приложении в один момент времени, пользователь может проходить только одну викторину. Тогда запрос на начало новой может выдать 409-й статус, а в полях status и message — дополнительную информацию, почему была получена ошибка.

9. Все параметры и json в camelCase

9.1 В параметрах запросов
Плохо:

GET /users/ GET /users/ GET /users/

Хорошо:

GET /users/ POST /ticket//gold

9.2 В теле ответа или принимаемого запроса
Плохо:

Хорошо:

10. Пользуйтесь Content-Type

Плохо:

GET /tickets.json GET /tickets.xml

Хорошо:

GET /tickets // и в хедере Сontent-Type: application/json // или Сontent-Type: application/xml

Заключение

Перечисленные выше рекомендации это далеко не весь список способов сделать API лучше. Для дальнейшего изучения рекомендую разобрать спецификации REST API и список кодов http-статусов (вы удивитесь, насколько их много и какие ситуации они охватывают).

А в комментариях предлагаю написать свою рекомендацию по построению REST API, которую вы считаете важной.