Особенности разработки API / Всеволод Шмыров (Яндекс)

Особенности
разработки API
Всеволод Шмыров, Старший разработчик интерфейсов

Кто я такой?
• Меня зовут Сева
3

Кто я такой?
• Меня зовут Сева
• Разработчик API Карт и Конструктор карт
4

API
• Framework
• Библиотека
• Сервис
• Виджет
• …
5

Что будет в докладе?
• Наш опыт
6

• Наш опыт
• Принципы и особенности разработки API
7

• Наш опыт
• Принципы и особенности разработки API
• Публичное API
8

Чего не будет в докладе?
• Ответа на вопрос «Нужно ли вам свое API?»
9

План доклада
• Проектирование интерфейса
11

• Обратная совместимость
12

• Исследование своего API
13

• Исследование своего API
• Дополнительные действия
14

Пример плохого интерфейса 16
getFriends() => []

var friends = getFriends();

getFriends() => []
getFriends() => Null
// Если нет друзей :(

if (friends) {
// ...
} else {
// ...
}

getFriends() => []
getFriends() => Null
getFriends() => User
// Один друг, но какой ...

if (isUser(friends)) { /* ... */ }
else if (friends) { /* ... */ }
else { /* ... */ }

Интерфейс должен быть
• Простым и логичным
22

• Консистентным
23

Консистентный интерфейс 24
iCanShowYou({x: 1, y: 1});
NoUCant([1, 2]);
ButIMust(Point);

NoUCant([1, 2]);
ButIMust(Point);

• Консистентным
• Но не в ущерб возможностям
27

Сложные задачи
• Много параметров
• Неопределенный результат из-за третьих сторон
28

Много параметров 29
someAwesomeMethod(
elem,
index,
startValue,
endValue
);

Много параметров 30
someAwesomeMethod(
elem, /* required */
index, /* = "key" */
startValue, /* = 0 */
endValue /* = 1 */
);

Группировка параметров 31
new ymaps.GeoObject(
geometry, /* {Object} */
properties, /* {Object} */
options /* {Object} */
);

Программные хелперы 32
new ymaps.GeoObject(geometry);
// Любые геометрии
new ymaps.Placemark(coord);
// Только «Point»

Неопределенный результат 33
geolocation.get()
.then(function (result) {
// success
}, function (error) {
// error
});

Неопределенный результат 34
geolocation.get()
.then(function (result) {
// success
}, function (error) {
// error
});

Браузерная геолокация
35

Браузерная геолокация 36
geolocation.get({
timeout: 30000
}).then(function (result) {
// ...
});

│Рукописи не горят

Обратная совместимость
Работает – не трогай!
38

Публикация нового интерфейса
• Степень свободы разработчика
39

Степень свободы разработчика
40
Степень свободы
разработчика
Ресурсы на поддержку
Риск ошибки

• Расширяемость
41

Расширяемый интерфейс 42
balloon.setPosition(
x, y // Обязательные аргументы
)

[x, y]
)

[x, y], projection
)

[x, y], options
)

• Расширяемость
• Не станет ли «блокером» в будущем?
46

overlay.getLayout()
// HTMLLayout

overlay.getLayout()
// Ilayout
// HTMLLayout, CanvasLayout ...

overlay.getLayout()
// Promise

Исправление ошибок
• Deprecated сущности
50

• Использование алиасов
51

Алиасы 52
presets.get('islands#greyIcon');
presets.get('islands#grayIcon');

• Использование алиасов
• Не все можно исправить
53

Отпусти и забудь 54
https://api-maps.yandex.ru/2.1/?lang=ru_RU&mode=debug

Мажорные релизы API карт
59
• Отказ от поддержки старых браузеров
• Добавление современных интерфейсов
• «Чистка» кода
2.12.0

«Особый режим» работы
60
'use strict';
function a () {
return this.b;
}

Порядок координат в API карт
https://api-maps.yandex.ru/2.1/
?lang=ru_RU&coordorder=longlat
61

62
...&coordorder=longlat // [широта, долгота] *
...&coordorder=latlong // [долгота, широта]

63
// [широта, долгота]
new ymaps.Placemark([55.8, 37.8])
// [долгота, широта]
new ymaps.Placemark([37.8, 55.8])

Визуальная обратная совместимость
64

Визуальная обратная совместимость
65

Каскадный «слом» совместимости
68
Проект
ScrollZoom
MouseEventBrowser
API
Клиенты

│Свой среди чужих

API «в гостях»
70
API API API
jQuery evil.js
Site 1 Site 2 Site 3

Переопределение нативных методов
71
Array.prototype.indexOf = function (item) {
for (var i = 0; i < this.length; i++)
if (item == this[i])
return i;
};

Общий CSS
72
* {
transition: 2s all ease;
}

Iframe v Script
73
https://events.yandex.ru/lib/talks/4258/

│Вы не знаете свой
продукт

Маленькие карты
75
2.0 2.1

Разные размеры контролов
76
Large
Medium
Small

Метрики
• Использование определенных модулей
77

Метрики
• Параметры использования API
78

Метрики
• Параметры использования API
• Параметры окружающей среды (браузеры)
79

│Документируй это

Избыточный пример
86

Избыточный пример
87

Конструктор карт Яндекса
90

│Продай мне эту ручку

92

94

95

Конструктор
• Простое решение популярных задач
96

• Меньше «свободы» для разработчика
97

Меньше возможностей в виджете
98
<script src="
.../constructor/?um={id}&width=514&height=326
"></script>

• Меньше «свободы» для разработчика
• Обход ограничения обратной совместимости
99

Принципы разработки API
• Не заставляйте делать лишнего
101

• Помните про обратную совместимость
102

• Помните про обратную совместимость
• Исследуйте использование API
103

Полезные материалы
• API Яндекс.Карт
https://tech.yandex.ru/maps/
• Iframe v Script
https://events.yandex.ru/lib/talks/4258/
104

vsesh@yandex-team.ru
Спасибо за внимание!
Всеволод Шмыров, Старший разработчик интерфейсов
vseshvsevolod.shmyrov
@vsesh

Особенности разработки API / Всеволод Шмыров (Яндекс)

More Related Content

What's hot

Similar to Особенности разработки API / Всеволод Шмыров (Яндекс)

More from Ontico

Особенности разработки API / Всеволод Шмыров (Яндекс)

Editor's Notes