Menu
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?
925
Uri(String, UriKind) Initializes a new instance of the Uri class with the specified URI. This constructor allows you to specify if the URI string is a relative URI, absolute URI, or is indeterminate. public: Uri(System::String ^ uriString, UriKind uriKind); C# Copy.
A URI is a string containing characters that identify a physical or logical resource. URI follows syntax rules to ensure uniformity. Moreover, it also maintains extensibility via a hierarchical naming scheme. The full form of URI is Uniform Resource Identifier.
The [FromUri] attribute is prefixed to the parameter to specify that the value should be read from the URI of the request, and the [FromBody] attribute is used to specify that the value should be read from the body of the request.
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?
127
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.
20
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With
