API. Что это такое, зачем существует, в чем преимущества. JSON

Котодомик

8 лет назад

Для начала стоит обратиться к википедии за определением того, что такое API.

API (интерфейс программирования приложений, интерфейс прикладного программирования) (англ. application programming interface, API) — набор готовых классов, процедур, функций, структур и констант, предоставляемых приложением (библиотекой, сервисом) или операционной системой для использования во внешних программных продуктах.

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

Примеры API

Пример, когда вам необходимо пользоваться API

Итак — по той, или иной причине у вас возникла необходимость написать приложение, которое будет узнавать текущий показатель курса валют.

Какие есть варианты решения этой задачи?

Найти сайт банка, у которого отображается данная информация и парсить

В целом это работает. Вы запросите страницу, получите HTML-код, с помощью специальных библиотек, либо с помощью саморучно написанного парсера — вы получите данную информацию.

Чем это плохо?

Вы становитесь заложником структуры и функциональности сайта банка:

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

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

Найти/запросить API для получения этих данных

Это правильный подход. В ходе запроса в поисковике «курс валют API JSON» я в течении 2 минут нашел соответствующий endpoint:

http://www.cbr-xml-daily.ru/daily_json.js

У этого сервиса есть также данные в формате XML, но так как на данном сайте есть уже информация о том, как работать с JSON — я выбрал JSON.

Это всего лишь разные форматы предоставления данных в сериализованном виде.

Итак у нас есть источник. Так называемый API endpoint. Так как C# строготипизированный язык — нам нужно знать структуру получаемых данных. Открываем ссылку выше на endpoint и копируем содержимое. На данный момент оно выглядит следующим образом:

{
    "Date": "2017-02-18T00:00:00+00:00",
    "PreviousDate": "2017-02-17T00:00:00+00:00",
    "PreviousURL": "\/\/www.cbr-xml-daily.ru\/archive\/2017-02-17.js",
    "Timestamp": "2017-02-17T13:00:00+00:00",
    "Valute": {
        "USD": {
            "ID": "R01235",
            "NumCode": "840",
            "CharCode": "USD",
            "Nominal": 1,
            "Name": "Доллар США",
            "Value": 57.6342,
            "Previous": 57.1507
        },
        "EUR": {
            "ID": "R01239",
            "NumCode": "978",
            "CharCode": "EUR",
            "Nominal": 1,
            "Name": "Евро",
            "Value": 61.4496,
            "Previous": 60.654
        }
    }
}

{

"Date": "2017-02-18T00:00:00+00:00",

"PreviousDate": "2017-02-17T00:00:00+00:00",

"PreviousURL": "\/\/www.cbr-xml-daily.ru\/archive\/2017-02-17.js",

"Timestamp": "2017-02-17T13:00:00+00:00",

"Valute": {

"USD": {

"ID": "R01235",

"NumCode": "840",

"CharCode": "USD",

"Nominal": 1,

"Name": "Доллар США",

"Value": 57.6342,

"Previous": 57.1507

"EUR": {

"ID": "R01239",

"NumCode": "978",

"CharCode": "EUR",

"Nominal": 1,

"Name": "Евро",

"Value": 61.4496,

"Previous": 60.654

}

Часть данных я стер, так как нам это интересно для примера. Я оставил только доллар и евро.

Заходим на сайт: json2csharp и вставляем эти данные в поле для ввода. После нажатия на кнопку «Generate» вы увидите классы, которые вам необходимы для работы.

public class USD
{
    public string ID { get; set; }
    public string NumCode { get; set; }
    public string CharCode { get; set; }
    public int Nominal { get; set; }
    public string Name { get; set; }
    public double Value { get; set; }
    public double Previous { get; set; }
}

public class EUR
{
    public string ID { get; set; }
    public string NumCode { get; set; }
    public string CharCode { get; set; }
    public int Nominal { get; set; }
    public string Name { get; set; }
    public double Value { get; set; }
    public double Previous { get; set; }
}

public class Valute
{
    public USD USD { get; set; }
    public EUR EUR { get; set; }
}

public class RootObject
{
    public string Date { get; set; }
    public string PreviousDate { get; set; }
    public string PreviousURL { get; set; }
    public string Timestamp { get; set; }
    public Valute Valute { get; set; }
}

public class USD

{

public string ID { get; set; }

public string NumCode { get; set; }

public string CharCode { get; set; }

public int Nominal { get; set; }

public string Name { get; set; }

public double Value { get; set; }

public double Previous { get; set; }

}

public class EUR

{

public string ID { get; set; }

public string NumCode { get; set; }

public string CharCode { get; set; }

public int Nominal { get; set; }

public string Name { get; set; }

public double Value { get; set; }

public double Previous { get; set; }

}

public class Valute

{

public USD USD { get; set; }

public EUR EUR { get; set; }

}

public class RootObject

{

public string Date { get; set; }

public string PreviousDate { get; set; }

public string PreviousURL { get; set; }

public string Timestamp { get; set; }

public Valute Valute { get; set; }

}

Главный объект — это RootObject. Его можно переименовать в тот, который вам больше подходит. Я оставлю как есть.

И так у него есть:

дата обновления;
дата прошлого обновления;
ссылка на данные прошлого обновления;
объект Valute.

У объекта Valute есть:

объект USD;
объект EUR;

Объекты USD и EUR уже содержат в себе данные курса валют. То есть для того, чтобы получить курс доллара — нам нужно обратиться к RootObject.Valute.USD.Value. Уже неплохо.

RootObject bankData = JsonConvert.DeserializeObject<RootObject >(jsonString);

1	RootObject bankData = JsonConvert.DeserializeObject<RootObject >(jsonString);

где jsonString- это строка с данными из URL API-endpoint.

В чем преимущества?

Вы больше не зависите от структуры HTML, нет нужны в HTML парсере вообще;
Если сервис решил предоставлять данные через API — значит он сам дал добро на то, что к нему будут обращаться программы, а не живые люди. Значит, что, скорее всего, пока будет существовать сервис — будет существовать и API (не всегда, но зачастую);
При обновлении структуры (например добавления новой информации) стараются не менять существующую структуру, чтобы программы, которые сейчас работают с API могли продолжать работать без сбоев. Например если добавят ещё несколько разных валют — у вас не станет падать приложение, просто без его доработки — вы не сможете работать с новыми данными от этой валюты — эти данные будут теряться при преобразовании строки с JSON в объект.

Серьезные преимущества, не так ли?

А главное — скорость.

Пример, когда вам необходимо написать сервис с API

Вы пишите платный сервис, который делает email рассылку.

На входе:

логин и пароль пользователя;
список email-адресов, на которые будет идти рассылка;
тема сообщения;
само сообщение.

Если ваш сервис успешно выполнил операцию, то отвечает

{
   "IsSuccess":"true",
   "ErrorCode":0,
   "ErrorMessage":""
}

{

"IsSuccess":"true",

"ErrorCode":0,

"ErrorMessage":""

}

То есть операция прошла успешно.

Если неверные учетные данные, то ответ будет таким:

{
   "IsSuccess":"false",
   "ErrorCode":11,
   "ErrorMessage":"Invalid credential data"
}

{

"IsSuccess":"false",

"ErrorCode":11,

"ErrorMessage":"Invalid credential data"

}

Если не хватило денег на балансе клиента на отправку сообщения (сервис то платный), то ответ будет таким:

{
   "IsSuccess":"false",
   "ErrorCode":10,
   "ErrorMessage":"Not enough money on the account to perform this operation"
}

{

"IsSuccess":"false",

"ErrorCode":10,

"ErrorMessage":"Not enough money on the account to perform this operation"

}

Теперь пользователи вашего сервиса смогут запрограммировать свой сайт/сервис/настольное приложения для использования вашего сервиса для рассылки почты.

Где ещё применяется API?

Именно удобство пользования и универсальность делают очень популярными в сегодняшние дни API.

Предоставление данных о погоде;
Предоставление данных о валюте;
Онлайн переводчики, которые принимают текст, язык текста и язык, на который нужно перевести, а на ответе выводят переведенный текст;
Рассылка E-mail/SMS/Skype/Telegram/Viber..;
Переводы денег;
Закрытое межсерверное взаимодействие;
Получение новостей;
Использование AJAX-frontend и API-backend.

О последним расскажу вкратце.

AJAX-Frontend

Наверное многие хотя бы раз слышали о таких вещах как:

Angular JS;
ExtJS;
DustJS;
ReactJS.

Это далеко не все представители динамичного формирования конечного HTML-кода страницы на стороне браузера.

То есть программа, написанная на javascript с использованием одного из этих фреймворков получает данные с сервера в формате JSON/XML и, в зависимости от этих данных по заданной логике формирует HTML-код. Данную программу можно составить таким образом, что фактической перезагрузки/загрузки страницы не будет.

Например сайт VK. Когда вы прокручиваете свою ленту — она грузится динамично. Как долистали до самого низа — в неё подгрузилось определенное количество объектов. Без этой технологии вы бы видели внизу страницы так называемый paginator, блок, в котором бы вы видели общее количество страниц вашей ленты и могли бы листать её таким образом.

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

В чем же преимущества сайта, который разделен на независимые логические части как Frontend-сайт и Backend-API?

Вы можете легко добавлять нужные блоки на сайт, используя данные с API-endpoint. Если у вас раньше на одной странице не было блока с новостями, но была на другой — вам не нужно переписывать логику, вы просто можете запросить эти данные у нужного Endpoint;
При необходимости вы можете создать мобильное приложение, которое будет использовать те же API-Endpoints для получения и отправки информации, не будет необходимости дорабатывать сайт — у вас уже всё готово. То же самое касается и настольного приложения, или взаимодействия с сайтом с другого сайта;
Вы можете написать ещё один независимый Frontend-проект, который будет также работать с данным API, но будет работать, к примеру, на другом фреймворке, или иметь другую структуру/дизайн. Оба проекта будут существовать за счет одного API, но не будут мешать друг-другу;
Скорость работы сайта. Такой подход позволяет передавать меньше данных при взаимодействии с backend, вам не нужно загружать каждый раз целую страницу, вы загружаете только данные для конкретного блока, состояние которого нужно обновить. А значит сервер не грузит все блоки каждый раз, а также передает эти блоки не целиком (блок HTML кода, а только необходимые данные, например URL картинки, которая теперь будет служить фоном в каком-либо блоке).

Если остались вопросы — задавайте в комментариях 🙂