Идентификация ресурсов в API

Идентификация ресурсов в API

Этот пост — краткий обзор главы из книги "API Design Patterns" Дж. Дж. Гивакса.

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

Непредсказуемость идентификатора — важный момент. Неплохо бы сделать так, чтобы нельзя было просто перебрать ID. И, конечно, стоит учитывать читабельность. Если ID видят пользователи, они должны быть понятными и удобными в использовании. Чем больше информации в меньшем количестве символов, тем лучше.

Что касается формата идентификатора, то строки остаются наиболее гибким и удобным решением. С ASCII-символами проще работать в веб-API — это исключает проблемы с неоднозначностью Юникода.

Использование Base32 — это хороший вариант. Этот формат применяет ограниченный набор символов, что делает идентификаторы удобными и легко различимыми. Контрольные суммы в ID помогают отличить некорректные значения. Встраивание типа ресурса в идентификатор также может упростить его идентификацию.

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

При реализации стоит помнить про размер. Для уникальности внутри одной области может хватить 13 символов, а для глобальной уникальности — около 25. Позволять пользователям выбирать ID — это рискованная затея; лучше использовать внутренние механизмы генерации.

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

Идентификаторы в API — это целый мир, и, если подойти к этому вопросу с умом, можно значительно улучшить взаимодействие с ресурсами.

#заметки_из_книг

Ⓒ Айнур пишет … 📝