День 1335. #ЗаметкиНаПолях
Разработка API для Людей.
Часть 1. Идентификаторы Объектов
Про выбор идентификатора между целым числом и GUID, я уже писал ранее. Сегодня посмотрим, как делать ID более удобочитаемыми для людей.
Вот, например, ID в платёжной системе Stripe:
pi_3LKQhvGUcADgqoEM3bh6pslE
Этот формат более понятен для человека:
pi_3LKQhvGUcADgqoEM3bh6pslE
└─┘└──────────────────────┘
└─ Префикс └─ Случайные символы
Ничего не зная об идентификаторе, мы можем сразу же понять, что здесь мы говорим об объекте PaymentIntent, благодаря префиксу pi_. Когда вы создаёте PaymentIntent через API, вы фактически создаёте или ссылаетесь на несколько других объектов, включая Customer (cus_), PaymentMethod (pm_) и Charge (ch_). С помощью префиксов вы можете сразу различить все эти разные объекты:
var pi =
Stripe.PaymentIntents.Create(@"{
Amount = 1000,
Currency = 'usd',
Customer = 'cus_MJA953cFzEuO1z',
PaymentMethod = 'pm_1LaXpKGUcADgqo'
}");
Это помогает сотрудникам Stripe так же, как и разработчикам, интегрирующимся со Stripe. Например, вот фрагмент кода, который нужно отладить:
var pi =
Stripe.PaymentIntents.Retrieve(
id: id,
stripeAccount: "cus_1KrJdMGUcADgqoEM"
);
Код пытается получить PaymentIntent из подключённой учетной записи, однако, даже не глядя на код, вы можете сразу заметить ошибку: вместо идентификатора учетной записи (acct_) используется идентификатор клиента (cus_). Без префиксов это было бы намного сложнее отлаживать.
Полиморфный поиск
При создании PaymentIntent вы можете дополнительно указать параметр paymentMethod, чтобы указать, какой тип платежного инструмента вы хотите использовать. Вы можете указать здесь идентификатор источника (src_) или карты (card_) вместо идентификатора PaymentMethod (pm_):
var pi =
Stripe.PaymentIntents.Create(@"{
Amount = 1000,
Currency = 'usd',
Customer = 'cus_MJA953cFzEuO1z',
// Здесь может быть
// PaymentMethod, Card или Source ID
PaymentMethod = 'card_1LaRQ7GUcA'
}");
Без префиксов не было бы возможности узнать, какой объект представляет идентификатор, т.е. мы не знаем, из какой таблицы запрашивать данные объекта. Одним из способов может быть требование дополнительного параметра типа.
Это сработало бы, но усложняет API без дополнительной выгоды. Вместо того, чтобы иметь PaymentMethod в виде простой строки, теперь это хэш идентификатора. Всякий раз, когда вы используете идентификатор, вам нужно знать, какой тип объекта он представляет, что делает объединение этих двух типов информации в одном источнике гораздо лучшим решением, чем требование дополнительных параметров типа.
Предотвращение человеческой ошибки
Есть и другие менее очевидные преимущества, одно из которых — простота работы с идентификаторами, когда вы можете определить их тип по первым нескольким символам. Например, на сервере Stripe Discord используется функция Discord AutoMod, чтобы автоматически помечать и блокировать сообщения, содержащие живой секретный ключ API Stripe, который начинается с sk_live_. Утечка такого конфиденциального ключа может иметь серьёзные последствия для бизнеса. Поскольку ключи начинаются с sk_live_, написать регулярное выражение для фильтрации случайных утечек несложно.
Говоря о ключах API, префиксы live и test — это встроенный уровень защиты, который защищает вас от их смешивания. Те, кто особенно заботится о безопасности, могут настроить проверки, чтобы убедиться, что вы используете ключ только для соответствующей среды:
if (!app.Environment.IsDevelopment())
{
if (Regex.IsMatch("sk_live", "<API_KEY>"))
throw new Exception("Live key detected! Aborting!");
}
Источник: https://dev.to/stripe/designing-apis-for-humans-object-ids-3o5a
