Strings or URI in .NET APIs?

Question

I am writing an .NET wrapper API for the Netflix API.

At this point I can choose to represent URLs as either strings or URI objects. Seems to me there is a good case for both.

So if you were using an API, which would you prefer?

Answer 1

The below quote is from: Framework Design Guildelines
I highly recommend this book to anyone developing frameworks on .Net

Do use System.Uri to represent URI / URL data.
(For Parameters, properties, and return values)

System.Uri is a much safer and richer way of representing URIs. Extensive manipulation of URI-related data using plain strings has been shown to cause many security and correctness problems.

Consider providing string-based overloads for most commonly used members with System.Uri parameters.

In cases where the usage pattern of taking a string from a user will be common enough, you should consider adding a convenience overload accepting a string. The string-based overload should be implemented in terms of the Uri-based overload.

Do Not automatically overload all Uri-based members with a version that accepts a string.

Generally, Uri-based APIs are preferred. String-based overloads are meant to be helpers for the most common scenarios. Therefore, you should not automatically provide string-based overloads for all variants of the Uri-based members. Be selective and provide such helpers just for the most commonly used variants.

EDIT (per comments): The book specifically states: "Extensive manipulation of URI-related data using plain strings has been shown to cause many security and correctness problems." I am not sure what additional justification you want for using System.Uri / UriBuilder. Additionally, why wouldn't you want to take advantage of the framework to read/manipulate a URI?

When designing an API that will be used by others it is important to make them approachable, as well as reliable. For this reason the book does mention, you should provide "nice" overloads for common functionality. However, to ensure correctness, you should always implement the underlying code with URIs.

Can you please clarify your wants, or reasons to use only strings?

Answer 2

I would say that you should represent it as URI. However, if I am a user of your API and I am having to continuously convert string based URLs to URI to use your API, then I would be a pissed off user.

What I am saying is that you need to assess what kind of audience will be consuming your API.

Answer 3

One thing I found was that while writing string-accepting methods, I'd always have to initialize a Uri object anyway just to validate the string, such that the UriFormatException would then propagate out of the method if the user passed a bad string. But if you accept Uris only, as I did after getting yelled at (rightfully) by FxCop, then you always know your input is valid---which to me seems like a very good sign that you're designing your API correctly.