Недавно член местной группы активистов, в которой я участвую, обратился за помощью в интеграции данных API Petfinder на ее веб-сайт спасения кошек. Владелец спасателя имеет существующий веб-сайт Wix и сама не является разработчиком. Ее цель состояла в том, чтобы иметь галерею всех усыновленных кошек в ее спасении. Каждый раз, когда она берет кошку, она добавляет ее в реестр Petfinder, что делает API Petfinder идеальным способом предоставления данных для ее галереи.

Когда я увидел ее запрос, в котором была ссылка на документацию по API Petfinder, я понял, что справлюсь с перевариванием API. Я бегло прочитал документацию, просто чтобы быть уверенным, а затем сказал ей, что буду рад помочь.

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

Шаг первый: скрытие секретов API в Wix

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

Оказывается, у Velo есть особый способ хранения этой информации, которая должна быть защищена от доступа пользователей сайта. Первым шагом после входа в редактор сайта является включение режима разработки с помощью меню «Режим разработки». Затем, щелкнув символ гаечного ключа, вы откроете меню инструментов Velo, а оттуда можно будет получить доступ к диспетчеру секретов.

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

Секреты доступны через имена переменных, присвоенные им в диспетчере секретов, очень похоже на использование файла .env на бэкэнде сайта для сокрытия конфиденциальной информации. Хотя Velo предоставляет место для внутреннего кода, лучше хранить и шифровать конфиденциальные данные в диспетчере секретов. Для получения дополнительной информации о том, почему это так, ознакомьтесь с документацией Secrets Manager от Wix.

Шаг второй: доступ к сторонним API-конечным точкам из Wix

Предполагая, что разработчик знаком с конечными точками API, которые он хочет использовать, и с тем, как получить доступ к этому конкретному API, следующим шагом будет активация вызовов API от Wix. Для API Petfinder требуется первоначальный запрос POST для защиты токена носителя с использованием идентификатора и секретного ключа, предоставленных разработчику. После возврата ключа-носителя его можно использовать для выполнения запросов GET данных к API.

Лучшее место, которое я нашел для написания этого кода, — это сервисный модуль на бэкэнде. Wix использует файлы JSW или веб-модули JavaScript для запуска кода на серверной части, который должен отвечать на вызовы клиентов (что здесь и делают запросы на выборку).

В разделе «Бэкэнд» раздела «Файлы кода» я добавил файл с именем petFinderService.jsw. В этом файле я импортировал необходимые модули и функции из пакетов Wix, а затем написал вызовы API.

import {fetch} from 'wix-fetch'; 
import {getSecret} from 'wix-secrets-backend';
import wixData from 'wix-data';
async function getBearerToken(){
 const clientId = await getSecret('PETFINDER_ID')
 const clientSecret = await getSecret('PETFINDER_SECRET_KEY')
 const configObj = {
  method: 'POST',
  headers: {
   'Content-Type': 'application/x-www-form-urlencoded'
  },
  body: `grant_type=client_credentials&client_id=${clientId}&client_secret=${clientSecret}`
 }
 return fetch('https://api.petfinder.com/v2/oauth2/token', configObj)
 .then(resp => resp.json())
 .then(data => data.access_token)
}
export async function petFinderService(){
 const bearer = await getBearerToken()
    const url = 'https://api.petfinder.com/v2/animals?organization=sc544'
 const headers = {
  headers: {
   'Authorization': `Bearer ${bearer}`
  }
 }
 fetch(url, headers)
 .then(resp => resp.json())
 .then(data => {
  data.animals.forEach(animal => {
   wixData.query('PetfinderAdoptables')
    .eq('url', `${animal.url}`)
    .find()
    .then(results => {
     if(results.items.length === 0){
      const infoToAdd = {
       url: animal.url,
       name: animal.name,
       age: animal.age,
       gender: animal.gender,
       photo: animal.photos[0].medium,
       status: animal.status,
       mainColor: animal.colors.primary,
       size: animal.size,
       spayedNeutered: animal.attributes.spayed_neutered,
       houseTrained: animal.attributes.house_trained,
       declawed: animal.attributes.declawed,
       specialNeeds: animal.attributes.special_needs,
       shotsCurrent: animal.attributes.shots_current,
       goodWithKids: animal.environment.children,
       goodWithDogs: animal.environment.dogs,
       goodWithCats: animal.environment.cats,
      }
      wixData.insert('PetfinderAdoptables', infoToAdd)
     }
    })
  })
 })
}

Два из трех импортов говорят сами за себя — fetch необходим для выполнения вызовов API, а getSecret — это функция, которую Wix предлагает для использования данных, хранящихся в диспетчере секретов (как обсуждалось выше). Третий импорт, wixData, используется для добавления информации, возвращаемой из Petfinder, в коллекцию контента на сайте Wix. Для разработчика коллекции контента функционируют так же, как базы данных на бэкэнде сайта, за исключением того, что редакторы сайта, не являющиеся техническими специалистами, могут вносить изменения в эти коллекции через графический интерфейс редактора Wix. Ниже приведена дополнительная информация о коллекциях контента и управлении ими.

Остальной код говорит сам за себя; сначала petFinderService вызывает функцию getBearerToken, которая обращается к API с идентификатором клиента и секретным ключом, а затем возвращает токен доступа после ответа API. Затем petFinderService делает запрос GET, используя токен носителя, а затем добавляет соответствующие данные в коллекцию контента, если она еще не существует. На момент написания этой статьи функция удаления питомцев, которые были удалены из API Petfinder, не реализована. Это действительно весь код, необходимый для этого проекта. Затем данные должны быть обработаны с помощью некоторых компонентов графического интерфейса Wix.

Шаг третий: управление и отображение данных с помощью Wix

Чтобы программно добавить информацию в коллекцию материалов, она должна сначала существовать. Никаких столбцов или другой информации создавать не нужно. Для этого проекта я создал коллекцию контента PetfinderAdoptables и использовал функцию wixData «insert», чтобы добавить данные API Petfinder в коллекцию после успешного возврата (как показано в разделе выше).

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

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

Единственными параметрами «общих разрешений» — параметрами, которые сделают данные доступными для просмотра незарегистрированным пользователем, — являются Контент сайта и Отправка формы. Поскольку я создавал галерею, я выбрал контент сайта.

Оттуда я перешел к тому месту на странице Adopt, где владелец сайта хотел свою галерею, и добавил галерею, связанную с коллекцией контента, которую я только что заполнил данными API. Во-первых, я добавил объект галереи, используя большую кнопку «+», доступную для добавления содержимого сайта. Я выбрал сетчатую галерею, потому что этого просил клиент. Затем я связал галерею с Content Collection PetfinderAdoptables.

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

Последний шаг: вызов функции службы и публикация сайта

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

Чтобы какие-либо плоды этой работы проявились — после того, как вызовы API работают и данные настроены для отображения — сервисный модуль необходимо вызвать со страницы Wix. Двумя лучшими вариантами являются либо глобальная страница/страница сайта, либо конкретная страница, на которой отображается элемент. Поскольку данные, которые я переваривал, нужно было загрузить только на странице Adopt, я решил разместить код там.

import {petFinderService} from 'backend/petFinderService'
$w.onReady(function () {
  petFinderService();
});

Обработчик события onReady на каждой странице Wix очень похож на обработчик события DOMContentLoaded в ванильном JavaScript, поэтому этот код просто вызывает асинхронную функцию petFinderService из модуля petFinderService, когда страница готова.

Наконец, я должен был не забыть нажать большую синюю кнопку «Опубликовать», чтобы завершить мои изменения на сайте. У меня было включено автоматическое сохранение, и я постоянно просматривал работу, но чтобы сделать изменения видимыми для посетителей, мне нужно было их опубликовать.

Несмотря на то, что в этом проекте было задействовано гораздо меньше кода, чем в обычном проекте, было важно научиться использовать гибридную среду разработки, такую ​​как Wix, которая позволяет вносить непосредственный вклад как техническими, так и нетехническими заинтересованными сторонами. Было интересно посмотреть, как функции содержимого DOM различаются в среде с графическим интерфейсом, и как некоторый код — например, показанные здесь запросы на выборку — поразительно одинаков. На самом деле я бы порекомендовал Wix разработчикам для определенных типов сайтов, таких как сайты-портфолио, которые должны быстро запускаться и работать, но при этом иметь профессиональный внешний вид. С Velo под поверхностью возможно даже довольно сложное применение кода.

Если вы находитесь в агломерации Шарлотта-Гастония-Форт-Милл-Рок-Хилл и ищете кошку, загляните в Jazz’s Wayward Kitties!