Сократите время до первого вызова (TTFC) для вашего общедоступного API с помощью Run in Postman.

Каждый дополнительный шаг, который вы выполняете для своих разработчиков, экономит их время и влияет на их время до первого вызова (TTFC) — самый важный показатель для общедоступных API. Кнопка Выполнить в Postman — это мощный способ упростить работу ваших разработчиков. Это не новая функция, но если вы были заняты, вы могли пропустить это сокровище, спрятанное у всех на виду.

Давайте рассмотрим несколько ключевых моментов, которые большинство людей не знают об этой кнопке. Затем я поделюсь кодом самой малоиспользуемой функции. Не стесняйтесь использовать этот код, заявить о себе, а затем примите похвалу от босса.

Шесть ключевых вещей, которые нужно знать о кнопке Run in Postman

Вы можете встроить коллекцию в эту крошечную скромную кнопку.

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

Вы можете связать среду с коллекцией.

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

Вы можете использовать кнопку в своих документах.

Когда вы создаете кнопку, выберите фрагмент кода, оптимизированный для Markdown или HTML, чтобы вставить его, например, в README или документы разработчика.

Вы можете настроить форм-фактор.

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

Это живой форк, а не статический импорт.

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

Кнопка "Выполнить в Postman" имеет собственный API.

Run in Postman API может динамически вводить информацию в виде значений переменных среды во встроенную кнопку Run in Postman. Подключайте динамически генерируемые данные, например токены доступа, с помощью клиентского кода вашего веб-сайта.

Первые пять вещей, перечисленных выше, очень легко сделать, и для этого потребуется несколько щелчков мыши в Postman. Но держу пари, что вы не знали о последнем. Чтобы сделать наши собственные динамические кнопки, нам нужно стряхнуть пыль со старого HTML и JavaScript.

К коду!

Динамическое создание окружения почтальона

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

Другие издатели API создают эти среды как часть процесса адаптации. Например, пользователи предоставляют информацию, которая затем помещается в кнопку. Давайте пройдемся по этому второму сценарию.

Шаг 1. Сгенерируйте кнопку

В общедоступной рабочей области Postman выберите коллекцию, которую хотите внедрить. Перейдите в дополнительное меню, выберите «Поделиться коллекцией» и перейдите на «Через Run in Postman».

В модальном окне вы можете добавить существующую среду и динамически обновлять значения. В этом примере давайте создадим новую среду динамически с помощью кода. Переключитесь на HTML-версию фрагмента кода. Скопируйте фрагмент кода в буфер обмена. Для следующих двух шагов нам понадобится код в элементе div для HTML и код в элементе script для JavaScript.

Шаг 2. HTML-элементы

В файле с именем index.html мы создаем элемент div, который содержит нашу кнопку Run in Postman. Используйте код, предоставленный в первой половине фрагмента кода из предыдущего шага.

<div class="postman-run-button" data-postman-action="collection/fork"
  data-postman-var-1="1559979-8aa8a323-6308-429c-90ca-e85d1d0bb33e"
  data-postman-collection-url="entityId=1559979-8aa8a323-6308-429c-90ca-e85d1d0bb33e&entityType=collection&workspaceId=ef3cdedd-f58c-4492-9ed0-4dcf456987b2">
</div>

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

<form method="post" onsubmit="return createEnv();">
  <label for="secretstring">Passphrase</label>
  <input type="text" id="secret-string" name="secretstring"><br><br>
  <input type="submit" value="Save">
</form>

Шаг 3. Функции JavaScript

В отдельном файле с именем app.js мы определяем две функции. Первая функция с именем createEnv() создает среду с именем Passphrase, которая включает данные, представленные пользователем в форме HTML. Среда создается динамически с использованием метода _pm() Run in Postman API.

function createEnv() {
  var secretString = document.getElementById('secret-string').value,
    runButtonIndex = 0,
    envData = {
      passphrase: secretString
  };
  _pm('env.create', 'Passphrase', envData, runButtonIndex);
  return false;
}

У нас также есть анонимная функция. Для этого мы можем использовать вторую часть фрагмента кода, предоставленного Postman на первом шаге, чтобы создать кнопку Run in Postman.

(function (p, o, s, t, m, a, n) {
  !p[s] && (p[s] = function () { (p[t] || (p[t] = [])).push(arguments); });
  !o.getElementById(s + t) && o.getElementsByTagName("head")[0].appendChild((
  (n = o.createElement("script")),
  (n.id = s + t), (n.async = 1), (n.src = m), n
  ));
}(window, document, "_pm", "PostmanRunObject", "https://run.pstmn.io/button.js"));

Вот и все! Пользователь вводит данные, захваченные HTML-формой, которые затем передаются в Run in Postman API с помощью метода _pm() для динамического создания новой среды, содержащей данные.

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