Как использовать первую платформу API, чтобы подготовить прототип к производству

1656681644 kak ispolzovat pervuyu platformu api chtoby podgotovit prototip k proizvodstvu

Майк Седилевский

В первой части этой статьи мы изложили способ создания статических и одновременно динамических веб-сайтов с помощью платформ, прежде всего API. Это один из множества подходов, которые можно использовать для быстрого создания прототипов бизнес-приложений.

В этой статье мы выведем это на новый уровень. Мы хотим усилить прототип, чтобы он был готов к выпуску в производственную среду.

1*LEexgp77Nph6PDWZAh2vnA
Фотография Патрика Хендри на Unsplash

Но для этого нам нужно преодолеть некоторые проблемы безопасности, которых просто нет на статических веб-сайтах. Как объединить четыре разных строительных блока нашей программы, чтобы автоматизировать бизнес-процесс? Как мы можем добиться этого, не теряя скорость итерации, которую мы имеем сейчас? Встречайте Zapier.

Но сначала – что мы уже построили

Если вы не помните, мы создали рабочий скелет nostalgia.io – рынок для экспертов в технологиях прошлого. Это статический веб-сайт с упрощенным пользовательским интерфейсом и функциональностью, созданный на основе четырех первых платформ API (Contentful, Algolia, Timekit и Voucherify).

Короче говоря, программа позволяет просматривать технологии, (полнотекстовый) поиск экспертов, находить и бронировать консультационное место в их календаре и, наконец, проверять страницу оформления заказа и принимать уникальные коды купонов.

1*E9BauUTpJhZtutx7p72VDw

Счастливый путь – когда любой Том, Дик или Гарри выходит на рынок со своим промокодом и получает подтвержденное бронирование по сниженной цене – работает довольно гладко. Помните, что вы можете увидеть это в действии и поиграть с исходным кодом в хранилище ошибок.

Но у нас еще много несчастных путей. Одним из самых болезненных является добавление нового эксперта. Пока это предусматривает несколько ручных шагов:

  • Добавление экспертной сущности к Contentful
  • Распространяется на поиск Algolia
  • Назначение ресурса календаря в Timekit
  • Обозначение купона как использованного, поэтому он больше не действителен

И дело в том, что вы не можете автоматизировать эти операции, используя наш текущий подход «статического сайта». Это потому, что наши провайдеры API не позволяют (слава Богу) для такого типа управления данными с помощью общедоступных API-ключей. Каждая платформа SaaS предоставляет два вида режимов авторизации:

  • На стороне клиента: ограничен набор функций для использования в веб-приложениях и мобильных приложениях (ключ API может видеть каждый)
  • Секрет: доступ к полному контролю для использования только на базовом уровне

Поскольку у нас еще нет бэкенда, нам нужно выяснить, как обойти эти ограничения без необходимости настраивать бэкенд-фреймворки и инфраструктуру веб-сервера.

Встречайте Zapier

«Zapier – это инструмент, позволяющий подключать приложения, которыми вы пользуетесь ежедневно, чтобы автоматизировать задания и сэкономить время». — Учебник Zapier с начала работы

На самом деле вы, возможно, уже погрузились в страну чудес Zaps, когда хотели автоматизировать некоторые личные операции, например «хранить мемы, которые я одобряю, в папке Dropbox». Однако вы могли пропустить это сегодня Zapier — это больше, чем это. Мы прошли долгий путь с момента их начала в 2011 году.

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

Буквально тысячи плагинов, которые можно найти на их рынке, делают Zapier мощным инструментом. В течение часа можно быстро подключить множество популярных поставщиков программного обеспечения, различные отделы и, наконец, компании в целом. В следующем разделе мы покажем вам, как использовать мощность zaps, сделав рынок Nostalgia более надежным и безопасным.

Добавление новых экспертов в Contentful и Algolia

Во-первых, автоматом сделать новенькую сущность. Для этого нам нужна онлайн-форма. Мы можем создать и разместить простую веб-приложение, которая соединяет HTML-форму с Contentful, но можем ли мы сделать это как-нибудь быстрее? Давайте постучаемся в дверь Zapier Directory. После ввода «форм» первое место в списке занимает Typeform. Мы проверяем описание там есть все, что нам нужно, поэтому давайте попробуем.

Как работает Zapier?

За кулисами все дело в вызовах HTTP-запросов и перехвате веб-хуков. Zapier предлагает уровень проверки подлинности и интуитивно понятный интерфейс для отображения одного формата данных в другом. Процесс отображения сводится к вызову серии коннекторов (Zaps), которые получают, преобразуют и передают данные по конвейеру. Каждый конвейер начинается с так называемого триггера, который активируется веб-хуком. Давайте построим один.

1*4DWmwip1_Yldtj3JxLP0_g
Редактор типоформ

Первое, маленькое препятствие

Теперь мы планировали показать, как Typeform собирает данные, необходимые для создания эксперта, но мы не будем этого делать. Причина странная. Вебхук правильно попадает на Zapier, но формат данных каким-либо образом поврежден.

Несмотря на то, что ввод текста был обработан должным образом, мы застряли с технологией многократного ввода. Значения, которые мы ввели в форму, просто не появились, когда полезная нагрузка запроса появилась в Zapier. Та же проблема возникла, когда мы изменили множественный выбор на набор из трех логических значений.

Поэтому мы решили изменить поставщика на SurveyMonkey — только для того, чтобы узнать, что отправка содержимого формы в Zapier доступна в годовом плане Premium. Наконец-то мы дали шанс формам WuFoo, и они прекрасно сработали.

Хотя нам понадобилось некоторое время, чтобы найти проблему, получить рабочую форму было быстрее, чем создать веб-приложение с нуля. Как общий совет, мы предлагаем осторожнее, планируя сейчас использовать официальные Zaps — даже от известных поставщиков.

1*snRRXlSsX-9vGTWj1dsn8Q
Успешная отправка формы WuFoo

Главное препятствие…

Пройдя настройки WuFoo Zap, мы сделали нашу настройку прослушиванием события отправки экспертной формы. Давайте превратим данные так, чтобы они соответствовали модели Contentful.

Используя официальный Contentful Zap, преобразование достаточно простое: вы просто берете одно поле из формы и сопоставляете его с соответствующим полем сущности, как на рисунке ниже:

1*Tut_QxJViuN_NZRanu82JA

Пока мы не захотим картографировать технологии. Как вы помните, каждый специалист может освоить многие технологии. Чтобы надлежащим образом сопоставить эту связь «один к многим», мы должны предоставить идентификатор сущности Contentful технологии в структуре конкретного объекта, например:

{ sys: { type: “Link”, linkType: “Entry”, id: “5oKmKwfdjGO2cCaCkwamKW”}}

вместо простых имен, происходящих от форм WuFoo. Кто-то может предположить, что мы могли бы сопоставить технологию в объекте JSON, но, к сожалению, это невозможно. Contentful Zap отправляет каждое поле в строку. Итак, полезная нагрузка, фактически попадающая на Contentful API, выглядит так:

{
  "fields": {
    "technologies": {
      "en-US": ["   { \n     \"sys\": {\n        \"type\": \"Link\",\n        \"linkType\": \"Entry\",\n        \"id\": \"5oKmKwfdjGO2cCaCkwamKW\"\n      }\n    }"]
    },
    "name": {
      "en-US": "Test Testowicz"
    }
  }
}

И вызывает ошибку 422 на стороне содержимого.

…и как это преодолеть

В этот момент мы решили проверить следующий Zap в конвейере, чтобы узнать, есть ли другие препятствия, которые мы не предусмотрели. Оказалось, что разъем Algolia не слишком зрелый. Поскольку бизнес настаивает на поставке прототипа, мы пришли к выводу, что не хотим тратить больше времени на тестирование этих заполнителей. Мы решили перейти в ручной режим полета.

К счастью, Zapier поставляется с Code zap. Представленный 2 года назад, он предназначен для выполнения нестандартных операций с помощью специальный код в JavaScript и Python – включая вызов посторонних API!

Это идеально подходит для нашего подхода быстрой итерации. Мы получаем старые добрые возможности создания сценариев и нам все еще не нужно настраивать серверную часть. Давайте посмотрим, как это поможет нам с проблемой содержимого.

Code Zap в действии

Давайте удалим Contentful Zap и разместим код на месте. Выбрав JavaScript, вы должны попасть в режим редактирования шаблона. Теперь нам нужно сделать три вещи:

  • Сопоставьте данные с предыдущего этапа конвейера данных (WuFoo zap) в переменные, которые можно использовать непосредственно в коде
  • Используйте переменные, чтобы подготовить полезную нагрузку в соответствующем формате
  • Отправьте полезную нагрузку в Contentful с помощью HTTP-вызова

Первое очень простое, потому что менеджер входных данных волшебным образом предлагает соответствующие поля:

1*m1C3t-ZElZI5vqP_Vo8CsA

Когда мы получим входящие данные, ничто не сможет помешать нам отправить запрос вручную. Кратко ознакомьтесь со ссылкой на API Contentful и вот мы:

var technologies = [];

if (inputData.gwt) {
  technologies.push({
    sys: {
      type: "Link",
      linkType: "Entry",
      id: "7Dtej0GnXqw6cSIMmA6Cko"
    }
  });
}

if (inputData.symfony) {
  technologies.push({
    sys: {
      type: "Link",
      linkType: "Entry",
      id: "5S2iYV7inK6KyokCkwu4ss"
    }
  });
}

if (inputData.struts) {
  technologies.push({
    sys: {
      type: "Link",
      linkType: "Entry",
      id: "5oKmKwfdjGO2cCaCkwamKW"
    }
  });
}

fetch('
  method: 'post',
  headers: {
    "Authorization": "Bearer <hidden>",
    "Content-Type": "application/vnd.contentful.management.v1+json",
    "X-Contentful-Content-Type": "expert"
  },
  body: JSON.stringify({
    fields: {
      name: {
        'en-US': inputData.name
      },
      price: {
        'en-US': parseInt(inputData.price)
      },
      projects: {
        'en-US': parseInt(inputData.projects)
      },
      description: {
        'en-US': inputData.profile
      },
      technologies: {
        'en-US': technologies
      }
    }
  })
})
.then(function(res) {
  return res.json();
})
.then(function(json) {
  var output = { expert: json } 
  callback(null, output);
})
.catch(callback);
contentful.js

Три вещи, на которые следует обратить внимание:

  • Zapier поддерживает выборку, но это единственная современная функция JS. Под капотом он работает под управлением Node v4.
  • Вы должны вызвать `callback`, иначе Zapier не узнает, когда процесс асинхронизации завершен
  • Существует ограничение на тайм-аут 1 с.

Теперь вы можете запустить тест, чтобы увидеть, сущность ли хранится в Contentful.

1*AeVUal5H7ApV0BDN7nOEsA

Загрузка экспертной фотографии в Contentful

Пока нам удалось добавить экспертную сущность и назначить ее соответствующим технологиям. Недостает одной важной вещи — фото.

Contentful сохраняет фотографии (и другие файлы) в отдельной абстракции под названием Assets. Сложная вещь состоит в том, что вы не можете просто скачать фотографию при создании сущности (как мы делали на предыдущем шаге). Процесс загрузки выглядит следующим образом:

  • Создайте объект ресурса, содержащий ссылку на ресурс
  • Инициировать обработку ресурса (в случае изображений он просто загружает файл)
  • Назначить актив экспертной организации

К сожалению, хотя официальный Zap, кажется, имеет эту опцию, в нашем случае ее нельзя использовать. Причина этого заключается в том, что Zap не возвращает идентификатор ресурса или какую-либо ссылку после загрузки. По сути, мы не знаем, как увязать эксперта с активом. Что теперь? Code zap снова впечатляет!

На самом деле мы должны использовать его дважды:

  • Первый запрос на создание актива
fetch('
  method: 'post',
  headers: {
    "Authorization": "Bearer <hidden>",
    "Content-Type": "application/vnd.contentful.management.v1+json"
  },
  body: JSON.stringify({
    fields: {
      title: {
        'en-US': inputData.name
      },
      file: {
        'en-US': {
          "fileName": inputData.name+".jpg",
          "upload": inputData.pictureLink,
          "contentType": "image/jpeg"
        }
      }
    }
  })
})
.then(function(res) {
  return res.json();
})
.then(function(json) {
  callback(null, json)
})
.catch(callback);
  • Второй для загрузки изображения
var assetURL = " + inputData.assetId + "/files/en-US/process";

fetch(assetURL, {
  method: 'put',
  headers: {
    "Authorization": "Bearer <hidden>",
    "X-Contentful-Version": "1"
  }
})
.then(function(res) {
  callback(null, []);
})
.catch(callback);

После того, как вы протестировали эти запросы отдельно, вы можете наконец-то склеить их с помощью InputData и разместить их перед Zap, что создает сущность, и после WuFoo zap. В общем, получаем следующий конвейер:

Wufoo > Код (создание ресурса) > Код (обработка ресурса) > Код (создание)g сущность)

Вы могли заметить, что код в каждом zap соответствует схеме копирования, вставки и изменения. Легко изменить детали запроса и перетасовать порядок вызова. Это не та мощность, к которой вы привыкли, а Good Enough™ для этапа прототипа.

Создание календарей Timekit

Наконец пора реализовать заказ. Поскольку Timekit не предоставляет официальных Zaps, мы вынуждены снова пригласить нашего хорошего старого друга. Возможно, вы помните, чтобы получить календарь для эксперта, вам следует создать ресурс в Timekit, а затем получить предназначенный для него экземпляр календаря. Догадайтесь, API Timekit настолько удобен для разработчиков, что они позволяют вам добиться этого с помощью одного запроса:

var email = inputData.email;

fetch(' // notice the include param
{
  method: 'post',
  headers: {
    "Authorization" : "Basic <hidden>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    name: email,
    timezone: 'Europe/Warsaw'
  })
})
.then(function(res) {
  return res.json();
})
.then(function(resource) {
  callback(null, resource);
})
.catch(callback);
timekit.js

Теперь вы наверняка имеете представление о том, что будет дальше. Нам просто нужно разместить zap в правильном порядке, чтобы обеспечить охват бизнес-процесса. Поскольку мы хотим хранить ссылку Timekit в экспертной сущности, мы должны разместить этот Zap, как в конвейере ниже:

Wufoo > Код (создание ресурса) > Код (обработка ресурса) > Код (создание календаря) > Код (создание)ting entity)

Последней частью автоматизации этого шага является предоставление экспертам возможности поиска. Если вы не помните, как мы подошли к этому с помощью Algolia, перейдите к первой части, чтобы освежить память. Затем можно сразу перейти к коду:

var objects = {
	requests: []
};

if (inputData.gwt) {
	objects.requests.push({
		action: "addObject",
		body: {
			name: inputData.name,
			description: inputData.description,
			projects: inputData.projects,
			price: inputData.price,
			contentfulID: inputData.contentfulID,
			technologies: { name: "Google Web Toolkit" }
		}
	});	
}

if (inputData.struts) {
	objects.requests.push({
		action: "addObject",
		body: {
			name: inputData.name,
			description: inputData.description,
			projects: inputData.projects,
			price: inputData.price,
			contentfulID: inputData.contentfulID,
			technologies: { name: "Apache Struts 1" }
		}
	});	
}

if (inputData.symfony) {
	objects.requests.push({
		action: "addObject",
		body: {
			name: inputData.name,
			description: inputData.description,
			projects: inputData.projects,
			price: inputData.price,
			contentfulID: inputData.contentfulID,
			technologies: { name: "Symfony 1.x" }
		}
	});	
}

fetch('
  method: 'post',
  headers: {
    "X-Algolia-API-Key" : "<hidden>",
    "X-Algolia-Application-Id" : "N675AF3ESI"
  },
  body: JSON.stringify(objects)
})
.then(function(res) {
  return res.json();
})
.then(function(resource) {
  callback(null, resource)
})
.catch(callback);
algolia.js

Когда вы настроите этот шаг, вы охватите весь процесс:

  • Кто добавляет эксперта через форму
  • Наше программное обеспечение создает соответствующий календарь в Timekit.
  • Экспертная сущность сохраняется в Contentful (вместе с фотографией)
  • Эксперт становится доступным для поиска, добавив его к индексу Algolia.

Вот и все, когда дело доходит до внутренней части процесса Nostalgia. А теперь давайте дадим нашим купонам шанс выполнить работу и привлечь к нам нескольких клиентов!

Погашение купонов

Давайте для начала вспомним, как работают купоны Nostalgia. Команда маркетинга разработала 2 разные кампании с тысячами уникальных кодов купонов:

  • Скидка 25% — примеры: nstlg-CCAMIDFf, nstlg-wZK4CoLs, nstlg-V8eV9A3p
  • Скидка $5 – примеры uub-nstlg, afl-nstlg, yeq-nstlg

Теперь, когда вы добавляете один из них в поле купонов, код проверяется на соответствие API Voucherify и применяется соответствующая скидка. Когда вы наконец-то выбираете временной промежуток и посылаете запрос на бронирование в Timekit, под капотом код посылается вместе с полезной нагрузкой и хранится в объекте Timekit.

Чтобы предотвратить повторное использование уникального кода, нам нужно пометить его как использованный в Voucherify. Мы могли бы достичь этого с помощью виджета Voucherify (просто замените метод проверки на redeem), но мы хотим пометить его как использованный только если бронирование было подтверждено командой операций (сделано на панели инструментов Timekit). Поскольку компания хочет перейти от автоматического подтверждения к подтверждению вручную, мы вынуждены оставить счастливую среду статического веб-сайта и снова обратиться к Zapier.

Перехват вебхуков

Как упоминалось ранее, вы напрасно будете искать Timekit в каталоге Zap. Мы должны найти другой способ получить уведомление о подтверждении бронирования. К счастью, здесь помогает Webbook zap.

1*5wZ76HK3v346MiPMJasiUg

После прохождения 5-этапного процесса настройки вы получите уникальный URL-адрес конечной точки, который можно использовать для отправки уведомлений через HTTP-запросы. Ваша следующая задача – разместить его в выноске вебхука в Timekit под определенным событием – в нашем случае это подтверждение бронирования.

1*4l3cQGN2CbBaPY53y5jeQw

Последний штрих – обработка выкупа

Последним шагом является вызов метода выкупа, чтобы обозначить купон как использованный. Для этого мы можем использовать официальный Voucherify Zap. Все, что вам нужно сделать, это позволить Zapier вызвать погашение и сопоставить информацию о клиенте, перехваченную с помощью webhook zap, в надлежащую структуру:

1*DNp2gEE3qNW1XKUrG6CRRA

После выполнения некоторых тестов мы видим, что Voucherify отслеживает погашение купонов:

1*4rM5iC2w4nt47WYkhYN7hA

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

1*QyqQSmNd01mivX7WEGHcKQ

Быстро и грязно

Поздравляю! Только в этих двух конвейерах Zapier мы построили четыре строительных блока безопасным и готовым к производству способом. Мы признаем, что решение выглядит быстрым и грязным, но оно работает, и оно было доставлено в приемлемое время.

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

Когда вы впервые переходите в каталог плагинов Zapier, все выглядит ярким и блестящим. Но дьявол, как говорится, кроется в деталях. Честно говоря, до того, как мы приступили к этой публикации, мы были чрезвычайно оптимистичны по настройке Zapier. Но в то время как мы все больше и больше вникали в детали, мы столкнулись с проблемами с Zaps, которые мы планировали использовать. Мы выделили их, чтобы вы могли избежать их на своем пути. И мы, надеемся, научили вас, как использовать менее известные функции Zapier, чтобы преодолеть пробелы.

Пожалуйста, пожалуйста, помните, что тандем «первые платформы API <> Zapier» – это не блестящий молоток, которым можно забить каждый гвоздь. Иногда существуют более быстрые и столь же надежные способы достижения бизнес-результата, чем написание кода с нуля.

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

1*b_7EFJ3zfoM9Xl17VTgteg

Добавить комментарий

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