Category Archives: WebDev

Extending your WebAPI documentation

As I already mentioned in a previous post, you can use the Microsoft.AspNet.WebApi.HelpPage NuGet package to generate a human-friendly documentation for your WebAPI directly from your source code. Because the NuGet package installs its full source code, you can customize the generated help pages with a few simple steps.

For example lets assume you designed your API that in case of any error all actions return an error code with the associated error message, and you store the possible errors in a different enum for every action. And of course you want to display these error cases in you API documentation!

Using a custom attribute – which I call here ErrorCodeType – you can connect the error code enum (here MyErrorCodeEnum) to the action on metadata level:

[ErrorCodeType(typeof(MyErrorCodeEnum))]

To display this information on the help pages, follow these steps:

 

1. Create a new class which will describe a single error case. Let’s call it ErrorCodeDescription and place it into the Models folder:

public class ErrorCodeDescription
{
  public int Code { get; set; }
  public string Message { get; set; }
}

 

2. The HelpPageApiModel.cs file contains the view-model which carries the data for the help page. Add a new property to this class which will contain all error cases in a list:

public List<ErrorCodeDescription> ErrorResponses { get; set; }

 

3. The GenerateApiModel method in the HelpPageConfigurationExtensions.cs file is responsible to build the view-model. You can find the VM in the apiModel variable which has the GenerateApiModel type. Here you can create and call a new custom method which retrieves your custom attribute and builds the ErrorResponses list like this:

private static void GenerateErrorResponses(HelpPageApiModel apiModel)
{
  ErrorCodeTypeAttribute attribute = apiModel.ApiDescription.ActionDescriptor
    .GetCustomAttributes<ErrorCodeTypeAttribute>().FirstOrDefault();
  Type enumType = attribute.ErrorCodeEnumType;
  string[] names = Enum.GetNames(attribute.ErrorCodeEnumType);

  foreach (string name in names)
  {
    apiModel.ErrorResponses.Add(new ErrorCodeDescription
    {
      Code = (int) Enum.Parse(enumType, name),
      Message = "TODO"
    });
  }
}

 

4. The Views/Help/DisplayTemplates/HelpPageApiModel.cshtml view is responsible for rendering the view-model. Add the following block to the view which delegates the rendering of the ErrorResponses list to the ErrorResponses partial view:

@if (Model.ErrorResponses.Any()) 
{ 
  <h3>Error Responses</h3> 
  @Html.DisplayFor(m => m.ErrorResponses, "ErrorResponses") 
}

 

5. Finally you have to create the ErrorResponses.cshtml file in the same folder. This partial view will receive a List<ErrorCodeDescription> instance as its @model and it is totally up to you how you want to transform it to a human-friendly HTML page.

 

At first it may seem too complicated, but in reality the steps are very logical and totally worth the time understanding it.

 

Technorati-címkék: ,

Defining a GUID type in XSD

It often happens that an element or an attribute in an XML document contains a GUID value. Because XML documents are useless without the corresponding XSD, it also often happens, that you have to define a GUID in XSD. Although XSD has support for several built-in types, unfortunately GUID is not one of them, and you have to use the classic regex solution:

<xs:schema ...>

  <xs:simpleType name="guid">
    <xs:restriction base="xs:string">
      <xs:pattern value="[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-
[0-9a-fA-F]{4}-[0-9a-fA-F]{12}" />
    </xs:restriction>
  </xs:simpleType>

After this you can refer to your new guid type just like the built-in ones:

<xs:attribute name="id" type="guid" use="required" />

Note that the regex pattern does not have $ and ^  characters in the beginning and in the end, because the pattern should always match the full value.

 

Technorati-címkék: ,

JSON or not JSON: that is the question

When you write unit tests for a REST API, you probably want to test whether the given response is in the expected format. For example you want to ensure, that the response string is a valid JSON or not.

You can find a very simple tip on StackOverflow and in other blogs as well: just check whether the first character of the response is a < or { character, because JSON is about Object Notation, right? The problem with this approach is not only that it does not perform a thorough analysis, but also that its basic statement is simply not true. According to json.org, a JSON can also contain only a single value, the specification does not require it to be an object or an array at all:

json-value

So I love JSON, 123, true and false are all valid JSON strings.

Unfortunately I could not find a simple IsValidJson method, but I could come up with this solution using Newtonsoft JSON.NET library:

try
{
    JToken.Parse(input);
    return true;
}
catch (JsonReaderException)
{
    return false;
}

Is there a better solution?

 

Technorati-címkék: ,,

Mixed content warning

It is so sad, when a webpage falls apart in the browser, like this one in Chrome:

mixed content chrome

Why is that? Oh, isn’t it obvious? The explanation is there, let me help you:

mixed content chrome warning small

It is called the mixed content warning, and although it is a warning, it is very easy to miss. Let’s see the same page in Firefox:

mixed content FF

Do you get it? Here it is:

mixed content FF blocked small

Internet Explorer is not so gentle, it immediately calls the user’s attention:

mixed content warning

Although you don’t have to search for a shield icon (which is one of the most overused symbol in the IT history) here, because you immediately receive a textual message, the situation is not really better. Average users don’t understand this message and the real cause behind it. What’s more, not only users don’t get it, but also web developers don’t understand the security consequences, otherwise there won’t be any page with this warning at all.

It is so easy to get rid of the mixed content warning: just ensure that if you load the page via https:// protocol, then you must load all referenced content (yes, all of them) via https as well. If you have a single http:// URL in your page, then the browser will trigger the mixed content warning. If you load content from a third party domain and you cannot use relative URLs, then start your reference URLs with “//”, which tells the browser to use the same protocol which was used to load the page itself. It is called the “protocol relative”, “scheme relative” or “scheme-less relative” URL, and you can find its description already in the RFC 3986 (dated January 2005) which specifies the URI syntax. Thankfully all browsers understand it as well.

It is time to fix these pages, and let the browsers sooner or later completely block these poorly implemented pages.

 

Technorati-címkék: ,,

How many requests do you need to authenticate?

It sometimes happens that a webservice requires Basic authentication, which is usually not an issue in .NET clients thanks to the Credentials property on the generated proxy class where you can set the user name and password:

MyService ws = new MyService
{
    Credentials = new NetworkCredential( "user", "password" )
};

You may think that after setting this property the client will send an HTTP request which contains the authentication data, but unfortunately things happen differently. First a request is sent without the Authorization header, and if the server returns a 401 Authenticate response, a second request is submitted which will contain the user name and password in the header. So the result is doubled traffic.

If you don’t like this (and why would you), you can use the PreAuthenticate property which forces the client to always send the authentication header without waiting for a 401 response:

MyService ws = new MyService
{
    Credentials = new NetworkCredential( "user", "password" ),
PreAuthenticate = true };

 

Technorati-címkék: ,,

Calling a PHP webservice from .NET

It happened that I had to call a webservice implemented in PHP from a .NET client via a standard SOAP interface, however it turned out again that Simple Object Access Protocol is not so simple in the real world.

The client received a 400 Bad Request response status from the server which itself, without any more details, didn’t help much to find the real problem. The Apache webserver log contained an Invalid URI in request entry, but that didn’t bring me closer to the solution either.

As many times before, Fiddler helped. Diving into the HTTP traffic I noticed that the request contained an Expect: 100-continue header which was not handled by the webserver. This is a very interesting header, which allows the client to ask the server to evaluate the request headers before the client submits the request body (see RFC 2616 Section 8.2.3 for more details). In short this single header can drastically change the classic request-response sequence to something like this:

Client –> Server:

POST example.com HTTP/1.1
request headers
Expect: 100-Continue

Server –> Client:

HTTP/1.1 100 Continue
response headers

Client –> Server:

request body

Server –> Client:

HTTP/1.1 200 OK
response headers
response body

The .NET client always sends this header to minimize the network traffic, but it seems that not all servers tolerate it. You can use the Expect100Continue property of the ServicePointManager class to override this behavior:

ServicePointManager.Expect100Continue = false;

You may even have better performance this way, because the HttpWebRequest class by default waits 350 msec for the Continue response.

 

Technorati-címkék: ,,

.NET Framework 4.5.2

Microsoft has just released a new version of the .NET Framework. Announcement and quick overview of the new features: Announcing the .NET Framework 4.5.2

More details about the new features: What’s new in the .NET Framework 4.5.2

Install packages:

This is an in-place upgrade! It installs side-by-side with the 3.5 SP1 and earlier versions, but in-place upgrades the 4, 4.5 and 4.5.1 version. That’s why the following knowledge base article my be important for you:
KB 2962547 – Known issues for the .NET Framework 4.5.2

Download!

 

Technorati-címkék: