Сегодня мы хотим поговорить о секрете — у нас есть API. Мы писали, а потом переписывали его в течение четырех лет. И за это время прошли практически все классические этапы «принятия неизбежного».
Кроме одного - четвертого.
И мы хотим поделиться своими с трудом заработанными выводами о том, что делать и чего не делать, если вы решили сделать свой собственный «мощный эпиай».
Процесс создания uCoz API иногда напоминал сюжет сериала The Knick («Больница Никербокера») — с неудачными операциями, кишками и экспериментами на живых людях.
Этап первый – Отрицание
Согласно концепции пяти этапов: На первом этапе человек отказывается принять то, что с ним произошло.В целом API для разработчиков веб-сайтов все еще встречаются редко.
А в 2010 году такого инструмента на рынке больше ни у кого не было.
С одной стороны, была определенная потребность в API: мы видели, что люди активно гуглили «скрипты для uCoz» и получали запросы напрямую — некоторые пользователи хотели создавать свои дополнения и модификации.
На другой стороне - и в этом была проблема , — в те времена все ресурсы были направлены на другие проекты.
Вопрос «быть или не быть» решался просто.
API нам нужен был самим — для запуска функции поддержки PHP в дизайнере.
Мы выделили одного разработчика, и за полгода он создал наш «начальный API» — это был get-only интерфейс, к которому можно было получать данные страницы из 11 модулей.
Данные были предоставлены только в формате XML. К моменту запланированного анонса PHP мы не успели даже добавить контент, но у API были и преимущества: с его помощью можно было запускать PHP-скрипты в бесплатной версии Yukoz. В общем, мы обратились к пользователям.
Получилось как по классике: 
Нас приняли не очень хорошо.
Точнее, нас в основном хвалили.
Но для PHP. Но в самом «эпиае» люди видели не то, что представляли себе под этим волшебным словом.
Техподдержку завалили вопросами: «Как добавить материалы? Как редактировать? Как получить это в json? Но всего этого не произошло.
Вторая стадия – Гнев
Согласно концепции пяти этапов: На этом этапе проявляется агрессия по отношению ко всему окружающему миру.К вопросу о необходимости разработки API компания вернулась примерно через год. Приоритетами были мобильные клиенты — и мы решили написать всё заново, учитывая требования ребят, делавших клиенты для iOS и Android. Первоначальная версия осталась жить сама по себе (и даже жива до сих пор, ведь некоторые ею до сих пор пользуются), и мы начали подбирать исполнителя для нового проекта.
«Свой собственный менеджер».
Умный парень Илья как раз пришёл в ростовский офис: он знал Perl, на котором была написана часть старого uCoz, и когда по традиции ему предложили несколько задач, он выбрал из них работу над API. Проблема заключалась в том, что на какое-то время парню пришлось стать самому себе менеджером.
Потом наступил гнев: «Как выяснилось в процессе, я понял синтаксис Perl, но не дух.
Поэтому долгое время я старался не работать, а делать мир лучше: думал все переписать, внедрить объекты-классы-паттерны.
Потребовалось много времени, чтобы освоиться с идеологией языка.
И тогда то, что поначалу казалось мне страшным и хотелось переписать, стало казаться нормой».
К моменту просветления появился менеджер и стал требовать отчет. И только доставка контента в нескольких модулях была готова.
В общем, снова гнев, теперь уже с другой стороны, - и Илью перевели на новый проект. Его версии API так и не было суждено увидеть свет.
.
Между этапами.
«Идеальная учебная задача».
К тому времени компания пыталась открыть R&D-офис в Казани.
Источник знаний обо всей системе был нужен локально — и возникла идея «вырастить» его за счет работы над API, который будет влиять на основные модули системы.
Вот каким появился Ринат в этой истории: 
С одной стороны, он с умеренным энтузиазмом взялся за проект (обычно он немного экстремален).
С другой стороны, в работе он спокоен и рассудителен: ведь за его плечами не только 700+ прыжков с парашютом, но и 20 лет опыта работы в IT. Он также был знаком с Perl и имел свежий опыт работы с чужими API — интегрировал Метрику и GA в панель вебмастера.
Первое, что нам пригодилось, — это его осторожность.
Ринат попросил паузу, чтобы подробнее разобраться в запутанных «внутренностях» системы, и только потом озвучил сроки и план реализации.
Через месяц он выступил с таким предложением: * Мы переписываем и дублируем некоторые функции исключительно для API. — за время создания системы в ней скопилось много старого кода.
А некоторые функции, если бы вы попытались туда впихнуть что-то другое, оказались бы «километровыми».
Это означает, что нам нужны очищенные двойники исключительно для API. * Мы используем REST — упростить архитектуру запросов, что поможет повысить производительность.
* Мы используем Oauth 1.0a — аутентификация, которая на тот момент казалась наиболее безопасной.
* Доставляем в разных форматах - JSON, XML, обычный текст. * Хорошо: получить, опубликовать, поставить, удалить, мир, труд, май.
Третий этап – Торг
Согласно концепции пяти этапов: Здесь у вас есть мысли о том, чтобы договориться с кем-то о лучшей судьбе Кажется, мы пришли к единому пониманию, как сделать это удобным.Но дьявол был в деталях и противоречиях.
Дело принципа расширилась сфера видимости токенов.
Наша серверная система, как говорит Ринат, «представляет собой полный инкапсулированный кусок дерьма»: на каждом сервере N пользователей, и когда место на нем заканчивается, забирается новое оборудование.
Ринат хотел использовать один токен, чтобы получить доступ ко всем сайтам.
«Хорошо, давайте поговорим об этом», — и мы пригласили еще коллег в чат по скайпу.
Как это бывает в коллективных чатах, мы спорили-спорили, но к коллективному решению так и не пришли.
И в бешенстве разработки тема забылась и всплыла вновь, когда интеграция для половины модулей была готова.
У нас не было другого выхода, кроме как тиражировать токен: так появилась архитектура с одним основным сервером авторизации — получив там один токен, его можно использовать везде.
Стилизовать его как массив или объект? Для нас это не была проблема «что правильно, а что нет».
Это была проблема с деталями.
Например, отправляем данные в JSON — и возникает проблема с типизированными языками.
Не все структуры, полученные от API, удобны для парсинга — потому что увеличивается объём кода на стороне клиента.
Но API ориентирован на веб-гаджеты, поэтому мы прислушались к мнению разработчиков Java и C++ и пришли к стандарту: поля даём в любом случае, именованные параметры дополняем кодом.
Поля и параметры.
На протяжении всего процесса реализации велись обмены и обсуждения.
Например, следует ли указывать пустой параметр? Поскольку мы также сосредоточились на мобильной разработке с использованием API, Ринат в процессе доказал, что в этом нет необходимости: ведь в мобильных приложениях важен трафик.
Какие поля необходимы? Здесь мне, руководителю проекта, пришлось искать и приводить примеры из реальной практики.
Часто мне помогала публика — я брал интервью у будущих пользователей API. Если кейс, поданный сторонним разработчиком, показался ценным, мы реализовали необходимые поля в самом API, чтобы люди потом не делали это через костыли.
А позже мы придумали более изящное решение — о нем поговорим ниже.
Четвертый этап -.
(и о сроках) Согласно концепции пяти этапов: На четвертой стадии вы впадаете в депрессию.
[Мы как-то прошли этот этап] Работа, запланированная на год, заняла почти два.
При этом возникли совершенно неожиданные трудности.
Мы быстро поняли, что: 
Проблемы со вторым разработчиком.
По плану, после того как Ринат сделал авторизацию, к интеграции API с модулями должен был подключиться второй разработчик.
Мы организовали Google Doc, расположив модули в алфавитном порядке.
Работа над ними была разделена между исполнителями пополам.
Мы определили график – по одному модулю в месяц от каждого.
Когда пришло время начинать, второй мужчина ушел.
И мы уже создали новый проект — конструктор uKit, которому посвятили основные ресурсы.
С потерей второго программиста к сроку реализации прибавилось почти 7 месяцев.
Проблемы с тестированием.
Теоретически процесс был построен так: после сервера разработчика всё идёт на альфа-сервер, и если тестер говорит «давай», то он проходит бета-тестирование и обновление распространяется на сотни серверов.
Но оказалось, что наши штатные тестировщики не очень подходят для работы с API — ведь они «заточены» для тестирования веб-страниц.
API — штука тонкая.
Например, когда происходило изменение внутри модуля, с которым мы интегрировались, что-то могло отвалиться — но тестировщики этого сначала не заметили (потом мы их научили).
Затем мы открыли 4 тестовых сервера и на самых ранних этапах пригласили продвинутых пользователей.
Такое крауд-тестирование, а потому не очень контролируемое (не знаешь, когда человек что-то сделает и бросит ли), тестирование тоже повлияло на увеличение времени.
Этап пятый – Смирение (и выводы)
Согласно концепции пяти этапов: По канонам наступает согласие с неизбежным В конце концов мы смирились с неизбежным — API, как и ремонт, можно начать, но не так-то легко закончить.Вот несколько рецептов, как организовать процесс, чтобы облегчить вам его.
1. Оставьте отзыв.
Больше связи.
Помимо ветки форума и сообщений в блоге, то есть общедоступных средств обмена комментариями, я создал на сайте раздел «Лаборатория» с новой документацией.
По сути, это была форма обратной связи, где вы могли обсудить свой случай в личной переписке.
О новом API мы сообщили ранним пользователям еще в феврале 2015 года, а процесс развертывания всех модулей на серверах завершился только в этом году.
Все это время мы получали отчеты, предложения и интересные кейсы от пользователей через «Лабораторию» (которую я также использовал в «торговле» с Ринатом).
Поток заявок снизился только за последние два месяца
Каждый раз, когда к нам поступал запрос «как это сделать или что здесь сделать», мы выдерживали время и садились смотреть, а что лучше? Иногда из этого выходили интересные истории.
2. Лично помочь непонятливым или [Скрипт в подарок].
Так получилось, что сообщение из «Лаборатории» нас настолько заинтересовало, что мы начали писать сценарий сами.
А затем представили пользователю готовое решение, Какова прибыль? Как говорится: «Хочешь найти ошибку — будь ошибкой».
И если вы хотите погрузиться в проект, сделайте на нем как можно больше, чтобы проверить его функциональность и удобство.
Тогда же на бирже uScript появились первые решения, использующие uAPI — авторизация через социальные сети и безглючное отображение картинок в блоке рекомендуемых материалов.
3. Проведите внутренний хакатон.
Как вы помните, нам не хватало тестировщиков.
Так родилась идея внутреннего хакатона для тестирования продукта.
Для некоторых наших разработчиков работа с API была совершенно новой и необычной задачей, поэтому у нас была возможность внимательно наблюдать за тем, как действуют люди с разными навыками.
Ринат обычно не общался с пользователями напрямую, но приехал из Казани на хакатон с ростовскими разработчиками.
Он говорит: «За исключением троллинга, я был доволен данными и критикой, собранными в ходе процесса».
4. Попробуйте что-то автоматизировать.
Моей любимой функцией работы с API было полуавтоматическое создание приложения и токена.
Изначально эта система возникла из моих личных потребностей — в один момент мне надоело тратить время на подписание запросов при создании приложения.
Тогда я решил написать полуавтоматический режим — чтобы ни о чем не думать, а скопировал данные — и приложение готово.
Как оказалось, люди сейчас в основном используют полуавтоматическое решение.
5. Проконсультируйтесь и измените документацию.
Изначально мы написали пример запроса на PHP и CURL. 
Это было.
Как выяснилось в процессе, CURL никто не использовал.
Но люди спрашивали, например, в каком формате и по какому пути отправить запрос.
Стало понятно, что первая реализация не всем очевидна.
Мы решили, что должен быть дополнительный модуль (написанный на современном ООП), где автоматически будет генерироваться подпись для oauth. Вызовите этот модуль один раз, а затем просто пропишите путь и метод запроса.
Заодно я прошелся по нашим программистам и спросил — какую документацию по API они считают достойным примером для подражания? Я посмотрел рекомендуемые примеры и с учетом их составил новую версию документация : 
И в качестве теста перед публикацией я попросил коллегу из нашего второго офиса проверить соответствие API описаниям в документации для всех методов.
6. Внедрить мобильность.
Во-первых, это поможет вам получить хорошие отзывы и расширить аудиторию:
У меня давно была мечта создать мобильное приложение для своего сайта.Во-вторых, это может быть ценный и новый опыт для внутренней команды.Я буду изучать uAPI, чтобы наконец воплотить его в жизнь.
Например, на хакатоне несколько наших ребят создали следующее приложение: 
Здесь вы можете увидеть код приложения 7. Не ограничивайте желания пользователей.
Вернемся к вопросу о полях.
Так как всех случаев предусмотреть не получится, в итоге мы сделали конструктор запросов, с помощью которого можно реализовать любую дикую фантазию на эту тему: 
Наконец, мы пришли к выводу, что API — это улица с двусторонним движением.
Сегодня с помощью uAPI можно авторизовать любой сайт, передавать материалы с uCoz и наоборот, использовать только нашу базу данных, но отображать данные на стороннем сайте.
Чем больше вариантов использования вы включите в инструмент, тем дольше будет реализация.
Но при этом сфера его применения растёт. P.S. Весь процесс развертывания и боевого тестирования новой версии занял у нас 14 месяцев и 20 обновлений.
Здесь визуализация .
Бывает, что после очередного обновления нам пишут: «Когда доделаешьЭ» Но процесс действительно очень сложно остановить (насчет ремонта мы не шутили).
Иногда по техническим причинам: скажем, когда обновление системы требует внесения изменений в API. А иногда – из творческих соображений.
Например, сейчас мы думаем: когда все интеграции с модулями будут завершены, почему бы не поработать над темой изменения дизайна и настроек сайта с помощью API? Теги: #rest #oauth 1.0 #php #perl #будни разработчика #uapi #токены #автоматизация #история создания #разработка сайтов #php #программирование #api
-
Какие Ошибки Распространены В Ит-Руководстве
19 Oct, 24 -
Почему Разработчикам Не Нравится Agile?
19 Oct, 24 -
Опубликован Перевод Документации Selenium
19 Oct, 24 -
Techday Make It Real - 17 Декабря, Москва
19 Oct, 24
