Работа с API в первый раз

На днях я впервые пробовал работать с API, и понял, что по этому поводу на удивление нет цельной инструкции для чайников. Надеюсь, эта заметка сможет ею стать. Сразу скажу, что работаю на Windows, в программе Visual Studio, и на языке программирования C#, и многие данные работают только для этой ситуации.
Итак, API. Что это? Самым часто встречающимся примером, который я видел при поиске, являются вилка и розетка. С одной стороны сложная система электрики, с другой -- прибор неизвестной сложности, но в итоге нам достаточно их соединить.С точки зрения программы это значит, что мы можем отправить на сервер запрос -- имеющиеся у нас данные, и получить ответ -- данные, которые нам нужны. Что должно быть в запросе, прописывается в документации API. Как правило, компании, чьи сервера предоставляют функцию запроса API, ведут эту документацию, и иногда даже нанимают для этого специального человека. Итак, разберем на примере с данными о погоде.
Есть сайт openweathermap.org, который предоставляет свои данные о погоде любому желющему на бесплатной основе. Достаточно зарегистрироваться, и вам выдадут уникальный ключ. После этого можно зайти к ним в документацию, и почитать, какие данные им можно отправить, и что мы получим в ответе. В данном случае им достаточно индекса или названия города, или можно указать id города. На их же сайте можно скачть файл формата json со списком городов. Json, кстати, нам будет очень нужен в дальнейшем, потому что большинство сайтов уже перешли на него,так что, если вы еще не умеете с ним работать, то лучше прервитесь, и поищите информацию об этом, но в целом дальше будут строки, которые можно просто скопировать.
Чтобы отправлять тестовые запросы серверам можно использовать программу Postman(далее Почтальон) или cURL. Опытные программисты, судя по всему, обычно используют вторую, но начинать советую с первой -- она гораздо нагляднее. Итак, скачайте и откройте Почтальон, и увидите строку с надписью "Enter request URL", в которой скорее всего уже выбран нужный нам метод Get, и столбцы Key, Value и Description. Пропишите в строке путь https://api.openweathermap.org/data/2.5/weather. Далее в поле Key мы будем вставлять название того параметра, который вы собираетесь передавать серверу, а в Value -- сами данные, которые отправляете.
Например, чтобы получить погоду в Санкт-Петербурге нужно указать key 'id', и value '498817'. Также мы хотим получать данные в метрическом формате, потому что зачем нам Фаренгейт, поэтому также нужно указать key 'units', и value 'metric'. И в случае с данным сайтом погоды им обязательно нужен наш уникальный ключ, выданный при регистрации, поэтому также прописываем в ячейке key "appid" и в value ваш уникальный ключ.В это время в строке к нашему пути прибавлялось все, что мы указывали. Изначальный путь отделяется от наших данных знаком вопроса, а потом идет перечисление наших ключей и значений. В итоге текст строки выглядит примерно так: https://api.openweathermap.org/data/2.5/weather?id=498817&units=metric&appid="ваш уникальный ключ". Если нажать большую синюю кнопку Send, то ниже получим ответ. Если все сделано правильно, то там в формате json и на английском языке расписаны температура, скорость ветра и тд.
Итак, мы научились создавать запрос к серверу. Чтобы сделать все то же самое в cURL, нужно установить его -- это утилита для командной строки компьютера. В некоторых операционных системах она сразу установлена, в некоторых нет. Хорошая информация по установке доступна по ссылке https://starkovden.github.io/curl-intro-and-instalation.html. Я буду отталкиваться от того, что она скачана и установлена. Нажимем кнопки win+R, в строке "Выполнить" пишем cmd, и в появившейся командной строке пишем curl -X GET "https://api.openweathermap.org/data/2.5/weather?id=498817&units=metric&appid="ваш уникальный ключ". Нажимаем enter, и получаем ровно те же данные в формате json.
Как нам сделать то же самое в нашей программе? Возвращаемся к Почтальону. С правой для нас стороны экрана небольшими красными буквами написано Code. Если зайти туда, то мы видим, что Почтальон замечательно сгенерировал нужный нам код для многих вариантов. Берем код для c#, безбожно копируем его в свою программу. Если у вас консольное приложение, то в целом этот код и так выдаст все нужное. Если у вас формы, то нужно получать данные отдельно. Для этого нам понадобится Newtonsoft.Json -- если нужно, установите его.
Итак, оставляем все до строки "IRestResponse response = client.Execute(request);". Теперь, чтобы перевести данные из формата json нам нужен класс, в котором будут все поля, которые прописаны в json. К счастью, Visual Studio замечательно умеет генерировать их сама. Для этого в Почтальоне или cURL нужно взять возвращаемые данные, целиком скопировать их в самый конец кода, выделить, и нажать кнопки edit - Paste Special - Paste JSON as classes. Дальше останется прописать строчку вроде "var obj = JsonConvert.DeserializeObject<Название вашего класса>(response.Content);", и у вас будет обьект с заполненными полями, к которым можно обращаться.
Перейти на страницу автора