"Начиная"
Краткое руководство по API в Python
Прямое руководство по веб-общению
Эти первые шаги по взаимодействию с Интернетом с помощью Python могут показаться сложными, но это не обязательно. Это удивительно простой процесс с четко установленными правилами и инструкциями.
Мы рассмотрим самое необходимое для начала работы, в том числе:
- Application Program Interfaces (APIs) - Javascript Object Notation (JSON) - Requests with Python - Real world use-cases
Прикладные программные интерфейсы
Мы можем рассматривать API как эти маленькие волшебные коробочки, куда мы отправляем данные, а затем получаем данные обратно.
Эта маленькая коробочка - не что иное, как скрипт где-то на сервере. Он действует как посредник между нами - клиентом - и ими - сервером. Мы можем сказать нашему посреднику, что мы хотели бы что-то узнать, что-то изменить или что-то удалить - и, если наши инструкции будут получены правильно, посредник с радостью отступит.
Существуют четко установленные рекомендации по созданию API, все они следуют одним и тем же шаблонам использования. Подавляющее большинство этих API (в Интернете) используют так называемую архитектуру REST.
ОТДЫХАТЬ
Архитектура API передачи репрезентативного состояния (REST) применяет шесть правил:
- Все запросы должны обрабатываться с использованием единого внешнего интерфейса.
- Существует независимость клиент-сервер - это означает, что изменения на стороне клиента (нас) не повлияют на функциональность на стороне сервера и наоборот.
- Каждый новый запрос обрабатывается отдельно от других запросов - API не сохраняет никакой информации о нашем сеансе, и поэтому он без сохранения состояния.
- Кэширование - API должен указывать, могут ли ответы кэшироваться пользователем.
- API состоит из многоуровневых систем, образующих модульную структуру.
- Если это применимо к использованию API, он должен предоставлять пользователям исполняемый код по запросу.
Все это создает единый шлюз с предсказуемым поведением, с которым можно общаться без слишком многих сюрпризов.
Типы запросов
Когда мы общаемся с API, мы, как правило, делаем один из следующих запросов:
- GET - получить информацию из API.
- POST - создайте новый ресурс (например, добавьте новую запись данных).
- PUT - обновить существующий ресурс (например, изменить конкретное значение в существующей записи).
- УДАЛИТЬ - удалить существующий ресурс (например, удалить запись данных).
Чаще всего используется протокол GET, который позволяет нам загружать данные.
Мы могли бы использовать API Карт Google, чтобы ПОЛУЧИТЬ координаты широты и долготы для определенного адреса.
POST, PUT и DELETE отличаются тем, что они используются только при изменении информации. Используя GitHub API, мы можем создать репо с помощью POST, обновить его с помощью PUT и удалить с помощью DELETE.
Также есть PATCH - он похож на PUT, но используется для «частичного обновления». Я никогда не использовал этот метод и никогда не видел его в документации по API, но он существует.
HTTP-коды
Когда мы используем GET, POST, PUT или DELETE - API отправляет нам ответ, что является частью этот ответ будет включать HTTP-код, который сообщает нам результат нашего запроса. Обычно это одно из следующих:
Success Codes 200 OK - success (common response to GET) 201 Created - new resource created (POST/PUT) 204 No Content - success but not content returned (not an issue) Client Error Codes 400 Bad Request - request not understood due to bad syntax (fix your JSON) 401 Unauthorized - not allowed, you need authentication 403 Forbidden - secret place, you're not allowed here 404 Not Found - you're lost, this place doesn't exist (or does it...) Server Error Codes 500 Internal Server Error - there's something wrong with the server OP Codes 418 I'm a teapot - teapot cannot brew coffee 420 Embrace Your Calm - sending too many requests to Twitter
Обозначение объекта Javascript
При взаимодействии с API мы используем стандартизированный шаблон для отправки и получения данных, чтобы и клиент (мы), и API могли правильно обрабатывать данные - этот формат представляет собой нотацию объектов Javascript (JSON).
JSON реализует ту же иерархическую структуру с парами ключ-значение, которую мы видим в словарях Python. Используя эту структуру, мы можем встраивать списки, строки или даже другие словари.
Давайте попробуем пример: щелчок здесь отправит запрос в PokéAPI с использованием нашего браузера, возвращая текстовую версию ответа JSON от API:
Мы видим формат ответа JSON, подобный словарю. С точки зрения структуры, нет реальной разницы между словарями Python и JSON, однако мы не можем использовать словари Python напрямую при взаимодействии с API.
Запросы Python
Мы изучили основы API-интерфейсов, но как мы можем начать с ними взаимодействовать в Python?
Мы можем использовать чрезвычайно популярную библиотеку requests. Если мы хотим отправить GET-запросы - все, что мы пишем:
import requests
requests.get('https://api_address.com')
Все, что нам нужно сделать, это ввести URL-адрес API, на который мы отправляем запрос, и альт - мы получим ответ JSON от API!
Используя ту же «конечную точку» (конкретную точку входа в API), которую мы использовали ранее для PokéAPI, мы могли бы вернуть ту же информацию в Python следующим образом:
Здесь следует обратить внимание на три ключевых момента:
- объект ответа, возвращаемый нашими запросами, показывает нам, что запросы были успешными -
<Response [200]>, что означает 200 ОК (см. Предыдущие коды). - Мы получаем доступ к возвращенным данным с помощью метода response
json(), который выводит версию ответа JSON в виде словаря Python. - Вывод словаря точно такой же, как тот, который мы видели при доступе к конечной точке API через наш браузер.
Поскольку мы вернули словарь с помощью метода json(), мы можем получить доступ к определенным частям ответа, используя те же методы, которые мы обычно используем в словарях Python. Если мы хотим вернуть имена способностей Чаризард:
Для всех вас, поклонников покемонов, я полагаю, что это конец статьи - для тех, кто менее заинтересован в возвращении исчерпывающего списка каждого покемона и их способностей, давайте перейдем к некоторым, возможно, более полезным API ...
Google Maps API
Google (конечно же) предоставляет огромный спектр API-интерфейсов, одним из которых, в частности, является их API-интерфейс геокодирования, он позволяет вам возвращать координаты широты и долготы для любого адреса. И это также было большой частью моего самого первого профессионального опыта с Python.
С тех пор он сильно изменился, но когда я думаю об «API», этот опыт - одна из первых вещей, которые приходят на ум. Он также служит прекрасным введением в типичное использование API.
1. Авторизация - большинству API-интерфейсов требуется, чтобы мы включали ключ авторизации в наши вызовы. Если мы это пропустим, мы обычно возвращаем код 4xx, говорящий нам, что нам нужна авторизация.
Шаги по получению ключа API включены в Документацию по API геокодирования, она проста, поэтому я не буду повторять здесь документацию.
2. Параметры API - мы попытаемся вернуть координаты Колизея в Риме. Адрес для этого - Piazza del Colosseo, мы включим его в URL нашего запроса в качестве параметра.
Мы можем использовать тот же подход и для аутентификации.
И прямо здесь, в нашем ответе JSON, мы видим lat и lng - мы можем получить доступ к обоим этим значениям, как и раньше, с PokéAPI.
А есть координаты широты и долготы Колизея - легко!
GitHub API
Мы видели запросы GET, но ничего о POST, PUT или DELETE. Эти запросы, как правило, немного отличаются, поскольку мы обычно включаем объект payload, в котором подробно описывается информация, которую мы POST ing, PUT или DELET ing с помощью API.
В этом примере мы будем использовать GitHub API для POST нового репозитория в нашей учетной записи GitHub. Опять же, нам снова нужен ключ авторизации - вы можете найти пошаговое руководство по доступу здесь.
Однако при выборе разрешений для вашего личного токена доступа единственное разрешение, необходимое для этого руководства, - репо. Я также рекомендую держаться подальше от разрешения delete_repo.
Как только у вас будет ключ авторизации, мы будем использовать его для аутентификации всех наших запросов к GitHub API следующим образом:
Все, что мы здесь сделали, это наш типичный запрос API, но с нашим ключом авторизации (или токеном), включенным в наш API headers. Мы можем думать о headers как о метаданных, которые мы включаем вместе с нашим запросом.
Последний шаг - это описание того, что мы хотели бы сделать. Сделаем это с помощью параметра data нашего запроса. Здесь мы включаем наш payload, который представляет собой словарь Python, преобразованный в строку формата JSON с использованием json.dumps:
После этого мы вернем код ответа 201 Created, который сообщает нам, что запрос был успешным и мы создали новый ресурс.
Чтобы проверить, мы можем перейти на Github.
И, конечно же, есть наше новое api_test репозиторий - мы многое можем сделать с помощью GitHub API, посмотрите документацию, если вам интересно.
Здесь у нас есть введение в мир API и то, как мы можем взаимодействовать с ними в Python. Отсюда еще есть чему поучиться.
Также стоит отметить, что это всего лишь одна сторона экосистемы API, конечно же, есть и другая сторона создания и обслуживания этих API - это совершенно другая игра.
Тем не менее, понимание концепций, которые мы рассмотрели в этой статье, является основой для продвижения вперед и вверх по другим направлениям взаимодействия и / или разработки API.
Надеюсь, вам понравилась эта статья! Если у вас есть вопросы, дайте мне знать через Twitter или в комментариях ниже. Если вы хотите больше подобного контента, я тоже публикую на YouTube.
Спасибо за прочтение!
Если вы хотите сразу перейти к разработке API на Python, ознакомьтесь с моей статьей о разработке API с помощью FastAPI: