Api
https://ru.wikipedia.org/wiki/API
API (МФА: [ˌeɪ.piˈaɪ]; аббревиатура от англ. application programming interface) — набор способов взаимодействия одной компьютерной программы с другими. Часто реализуется отдельной программной библиотекой или сервисом операционной системы. Используется обычно программистами при написании приложений. Позволяет общаться с программой, которая предоставляет этот интерфейс, как с «чёрным ящиком» — не знаю, что происходит внутри, но результат моего действия должен быть вот таким.
В повседневной «некомпьютерной» жизни с чем-то похожим на API мы сталкиваемся при взаимодействии с организациями, с бюрократией. «Напиши заявление по форме такой-то и отправь по такому-то адресу, в такое-то окно или кабинет, чтобы получить ответ по форме такой-то либо отказ по форме такой-то». И подборки образцов заполнения заявлений, запросов, прочих подаваемых документов близ окошек для подачи. Скорость реагирования в этих случаях, понятно, «человеческая», а не компьютерная. Процессы внутри мы не видим, хотя можно догадываться — тот же «чёрный ящик». И пожалуй, было бы неплохо обнаружить внятные исчерпывающие справочники для этих интерфейсов, такие, как бывают в айтишной документации.
Сейчас, когда говорят об API, обычно подразумевают Web API, интерфейсы, к которым можно обращаться через интернет. По нынешним временам можно столкнуться с SOAP или XML-RPC (и это, скорее всего, будет наследие прошлого) и запросами в XML, c RESTful API, где запросы и ответы, вероятно, будут в формате json, и это наше светлое настоящее, или с gRPC, где сообщения ходят в формате protocol buffers (тоже настоящее, но более редкое, для особых случаев).
REST (от англ. REpresentational State Transfer — «передача репрезентативного состояния» или «передача „самоописываемого“ состояния») — архитектурный стиль взаимодействия компонентов распределённого приложения в сети. Стандарта для RESTful WEB API нет, в отличие от SOAP (http://www.w3.org/TR/soap/).
В случае RESTful API:
- есть разделение на клиент и сервер. Клиент обращается с запросами, сервер отвечает.
- сервер не хранит у себя состояние клиента между запросами. Каждый отдельный запрос должен содержать в себе всё, что нужно для выполнения.
- запрошенный ресурс идентифицируется в запросе.
Есть дивной красоты идея Static api, где предлагается разложить по каким надо адресам json-чики или что там ещё для скачивания, таким образом сымитировать api только для чтения.
Ссылки
- https://apidog.com/ – вроде, полезная штука и не postman.
- https://joolfe.github.io/postman-to-openapi/ - конвертировать коллекции postman в openapi (
Проще говоря, это набор способов взаимодействия, с помощью которых компьютерная программа (бот или же сайт) может использовать другую программу. swagger).
- https://www.postman.com/postman/workspace/postman-public-workspace/collection/23020434-a7823a90-2517-4d89-ad02-c37b9d4b4b4f что пишет сам постман.
- https://stepik.org/course/124947/syllabus - курс, который пробежала, чтоб уложилось в голове, что есть, и мож чуть пополнилось, чего нет.
- https://github.com/docops-hq/learnapidoc-ru - Курс по документированию REST API
- https://starkovden.github.io/ - оно же.
- https://habr.com/ru/articles/765064/ - статья про GraphQL.
- https://habr.com/ru/articles/769384/ - на чем можно поупражняться в дергании api
- https://habr.com/ru/articles/770226/ - про всякое спорное «как дела делаются».
- https://habr.com/ru/articles/722650/ - о документировании публичных api
- https://habr.com/ru/companies/tinkoff/articles/780024/ — про gRPC «для аналитиков»
- https://habr.com/ru/hubs/api/articles/
- https://github.com/idsulik/swama и https://habr.com/ru/articles/843824/
Про REST-клиенты
- https://install.advancedrestclient.com/home
- https://docs.advancedrestclient.com/using-arc/sending-requests
- https://github.com/advanced-rest-client/arc-electron
- https://github.com/pashky/restclient.el - емаксовый, ясно, я им обзавелась.
- https://github.com/alf/ob-restclient.el И ob-restclient, который позволяет использовать restclient в orgmode.
- Ещё есть ob-http.
- https://magnus.therning.org/2024-09-01-improving-how-i-handle-secrets-in-my-work-notes.html – хранить логины-пароли, которые нужны в блоках кода
# -*- restclient -*- # # Gets all Github APIs, formats JSON, shows response status and headers underneath. # Also sends a User-Agent header, because the Github API requires this. # GET https://api.github.com User-Agent: Emacs Restclient
Ну, картинку из орга не показывает, а так да, есть такое.
# # It can even show an image! # GET http://upload.wikimedia.org/wikipedia/commons/6/63/Wikipedia-logo.png
SOAP и xml-rpc
XML-RPC (от англ. eXtensible Markup Language Remote Procedure Call — XML-вызов удалённых процедур) — стандарт/протокол вызова удалённых процедур, использующий XML для кодирования своих сообщений и HTTP в качестве транспортного механизма. XML-RPC, как и любой другой интерфейс Remote Procedure Call (RPC), определяет набор стандартных типов данных и команд, которые программист может использовать для доступа к функциональности другой программы, находящейся на другом компьютере в сети. И там же в википедии пишут, что вроде как есть мнение, что xml-rpc никакой ценности не добавляет, xml как xml, тока многословнее – за ссылками на англоязычную страницу https://ru.wikipedia.org/wiki/XML-RPC
Есть еще json-rpc, https://en.wikipedia.org/wiki/JSON-RPC, но как-то исторически менее популярная тема.
SOAP — расширение xml-rpc, ставшее стандартом. Чаще всего используется поверх http, но может и поверх других протоколов прикладного уровня. Есть стандарт — http://www.w3.org/TR/soap/.