Строки или URI в API.NET?

Question

Я пишу API-оболочку.NET для Netflix API.

На данный момент я могу представить URL-адреса в виде строк или объектов URI. Мне кажется, для обоих есть хороший случай.

Итак, если бы вы использовали API, что бы вы предпочли?

Answer 1

Приведенная ниже цитата из: Рамки дизайна Guildelines
Я настоятельно рекомендую эту книгу всем, кто разрабатывает фреймворки на.Net

Используйте System.Uri для представления данных URI / URL.
(Для параметров, свойств и возвращаемых значений)

System.Uri - гораздо более безопасный и богатый способ представления URI. Было показано, что обширные манипуляции с данными URI с использованием простых строк вызывают много проблем с безопасностью и корректностью.

Рассмотрите возможность предоставления перегрузок на основе строк для наиболее часто используемых членов с параметрами System.Uri.

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

Не перегружайте автоматически все элементы на основе Uri версией, которая принимает строку.

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

РЕДАКТИРОВАТЬ (за комментарии): В книге конкретно говорится: "Было показано, что обширные манипуляции с данными URI с использованием простых строк вызывают много проблем с безопасностью и корректностью". Я не уверен, какое дополнительное обоснование вы хотите использовать для System.Uri / UriBuilder. Кроме того, почему вы не хотите использовать преимущества инфраструктуры для чтения / манипулирования URI?

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

Не могли бы вы уточнить ваши пожелания или причины использовать только строки?

Answer 2

Я бы сказал, что вы должны представлять его как URI. Однако, если я являюсь пользователем вашего API и мне приходится постоянно преобразовывать строковые URL-адреса в URI, чтобы использовать ваш API, то я бы разозлился.

Я хочу сказать, что вам нужно оценить, какая аудитория будет использовать ваш API.

Answer 3

Я обнаружил, что во время написания stringПринимая методы, я всегда должен был инициализировать Uri объект в любом случае просто для проверки строки, так что UriFormatException затем будет распространяться из метода, если пользователь передал неверную строку. Но если вы принимаете Uriтолько, как я сделал после того, как FxCop крикнул (по праву), что вы всегда знаете, что ваш ввод действителен - что мне кажется очень хорошим признаком того, что вы правильно разрабатываете свой API.