Вопрос или проблема
После работы с MongoDB, я обнаружил, что есть преимущество в поддержании разделения между идентификатором, используемым базой данных, и идентификатором, который используется в моем коде для ссылки на этот объект. В моем коде я называю ссылку, которая используется для идентификации объекта внутри моего домена “ref”, а идентификатор, внутренний для базы данных, – id. Другие подходящие названия могут быть externalID и internalID, но я нахожу, что использовать ref и id проще для чтения.
Я разрабатываю API, который будет ориентирован на пользователей. Я видел, что в большинстве API идентификатор часто обозначается как id. Но это нарушает нашу внутреннюю политику использования “ref” вместо “id”. Поэтому я думал о том, чтобы вместо этого возвращать ref. Например, вы можете сделать запрос к API, и он будет возвращать { …, requestRef: строка } вместо { …, requestID: строка }
Будет ли это запутанным или нарушит стандарт в дизайне API?
Ответ или решение
Использование термина “ref” вместо “id” в публично доступном API может вызывать определённые сложности и недопонимания, что стоит учитывать при проектировании интерфейса взаимодействия. Давайте рассмотрим этот вопрос детально, чтобы понять все аспекты данной проблемы.
### Понимание терминов “id” и “ref”
В контексте разработки программного обеспечения “id” (идентификатор) обычно используется для обозначения уникального идентификатора объекта в системе. Это понятие интуитивно понятно многим разработчикам и пользователям. С другой стороны, “ref” (ссылка) может не иметь столь четкого определения и значимости, как “id”, что может привести к путанице при взаимодействии с API. Таким образом, “ref” может быть менее очевидным для конечного пользователя.
### Стандарты проектирования API
При проектировании публичных API важно следовать принятым стандартам и практикам. Использование “id” в качестве идентификатора объекта является общепринятой практикой в большинстве известных API, включая RESTful и GraphQL. Отступления от этого стандарта могут вызвать недопонимание сигнала, который отправляется пользователю: вместо ожидаемого “id” пользователь получит “ref”, что может заставить его задуматься о разнице между двумя терминами.
### Пользовательский опыт и понятность
Важно помнить, что API не предназначены только для разработчиков внутри вашей компании, но и для третьих лиц, которые могут не знание ваших внутренних соглашений. Соответствие общепринятым стандартам помогает избежать путаницы и делает вашу API более удобной для использования. Если ваш API будет возвращать поля с названием “requestRef”, это не только может быть воспринято как неожиданность, но и потребует дополнительных усилий для изучения документации.
### Поддержка и документирование
Если вы всё-таки решили использовать “ref” вместо “id”, вам необходимо обеспечить тщательное документирование всех аспектов API. Это включает в себя описание всех используемых терминов и их значений. Однако даже при наличии документации, пользователи могут предпочесть более привычные термины, такие как “id”.
### Итог
В заключение, использование “ref” вместо “id” в публично доступном API может вызвать путаницу и нечеткость в восприятии. Рекомендуется строго следовать общим стандартам проектирования API, чтобы обеспечить максимальное удобство и понятность для всех пользователей. Если у вас есть обоснованные причины для использования “ref”, убедитесь, что документация продумана и чётко объясняет разницу между этими терминами, однако такой подход может вызвать больше вопросов, чем ответов, у ваших пользователей.