Web API Deep Dive – HTTP Response Codes (Part 2 of 6)

Microsoft’s ASP.Net Web API 2.2 allows you to easily create REST style APIs on an IIS website. Microsoft has some great documentation on how to get started with it, so I won’t rehash that here. Instead, I’m going to go a little deeper into some powerful features that can be used with Web API.

Part 1 - Customizing auto-generated documentation
Part 2 - HTTP Response Codes (this article)
Part 3 - HTTP Error Codes from Exceptions
Part 4 - OData URL Query Options
Part 5 - DTO Transformations and Automapper
Part 6 - Testing with EF Rollbacks across HTTP

Using Appropriate HTTP Response Codes

When building an HTTP REST API, you should use appropriate HTTP response codes to indicate the status of a response. This uses the semantics of HTTP to communicate the status rather than inventing something new. Here are the three response codes I use most often:

HTTP 200 - Everything is OK
HTTP 201 - Something was created
HTTP 404 - Something could not be found

I only explicitly do this for methods that return a single object. For Web API methods that return a collection, I don’t worry about what’s written in this blog post. That’s because if I successfully return a collection, Web API will by default return HTTP 200 OK. If it can’t find any items, I return an empty collection, which still by default returns HTTP 200 OK. And if there is an error, the error handling filter returns the appropriate HTTP Status code for the error (more details on this in next week’s post).

Read More

Web API Deep Dive - Customizing Auto-Generated Documentation (Part 1 of 6)

Microsoft’s ASP.Net Web API 2.2 allows you to easily create REST style APIs on an IIS website. Microsoft has some great documentation on how to get started with it, so I won’t rehash that here. Instead, I’m going to go a little deeper into some powerful features that can be used with Web API.

Auto-generated Documentation

API documentation is notoriously difficult to keep up to date. After you finish writing or updating a method on the API, you must then go to your documentation and make updates to it that correspond to the changes you made to the API. It’s easy to forget, and it’s hard to find the time. But Web API has the built-in ability to automatically generate help documentation pages for you. To set it up, follow the documentation at http://www.asp.net/web-api/overview/creating-web-apis/creating-api-help-pages.

Read More

Cleaning up EF 6 tests with Transaction Rollbacks

You’ve set up Entity Framework, and you’ve even written integration tests against your code. Your tests create all kinds of sample data in your test database (you aren’t running integration tests against your production database, are you?), and now you need to make sure that the sample data gets cleaned up so the database looks like it did before your test. You could try to do some code to cleanup your data after your test runs, but if your test fails, it can be hard to know exactly how to clean up your data because you can’t guarantee that the data is in a particular state.

There is a better way. I was chatting with @jeremy6d this morning, and he suggested that I use transactions that can be rolled back at the end of a test. The following is how to do so when using Entity Framework 6.

Read More

ASP.Net Bundling and Minification - No Dots Allowed

If you aren’t bundling and minifying your javascript and CSS files, you should. It can significantly improve the load time of your web application. And if you’re working in ASP.Net, Microsoft helps bundle and minify your files with their Web Optimization tools, available on NuGet.

If you want to learn how to use the ASP.Net Web Optimization tools, read these links:

There is just one extra note I want to add - when creating a bundle, don’t put a ‘.’ in the bundle name, or it will silently fail.

So don’t do this:

bundles.Add(new ScriptBundle("~/bundles/myfiles.js.min").Include(...);

Instead, do this:

bundles.Add(new ScriptBundle("~/bundles/myfiles").Include(...);

4 Ways to Ignore Files with Git

It’s Greek to me

While working on a pull request for Knockout-Validation, I had the most bizarre thing happen: after cloning the repository, git status told me that one of the files was already modified. It turned out to be the localized text strings for Greek. Considering that I had just cloned the repository and that I don’t speak any Greek, I was fairly certain I hadn’t actually changed the file. I tried to undo changes with git checkout Localization/el-GR.js, but the file was still checked out. It seemed impossible to ‘undo’ whatever mysterious change had happened.

Google failed me

After a few rounds of Google-fu, my best guess was that something had happened related to character encoding, and some strange interaction between Git and Windows caused Git to think the file had changed. The best advice I found on the matter was to make a copy of the file elsewhere, delete the file from the repository, check in the deletion, copy the file back, add the file to the repository, commit the add, then carry on with other work. However, since I’m making changes on someone else’s project, I didn’t want to get into a conversation with them about why I’m changing the encoding around on one of their internationalization files when I really wanted to work on changing how the min and max validators worked.

4 Ways to Ignore a File

While chatting with @deathbob and @jeremy6d about the matter, Bob brought up the idea of ignoring the file by adding it to .gitignore. A good idea, but doing so would then mean that I would check in an updated .gitignore, which other team members wouldn’t like (especially the one who contributed the greek translation). Additionally, .gitignore won’t ignore files that are already part of the repository, so adding the file to .gitignore didn’t work.

However, the crux of Bob’s idea - ignoring the file - was exactly what I needed. I wasn’t sure why the Greek translation file was messed up (probably something with my system), but if I could ignore the file then I could focus on that files I actually cared about and not get sidetracked.

It turns out that there are 4 ways to ignore files with Git, and one of them solved my problem.

  1. .gitignore
  2. Global .gitignore
  3. Repository Exclude
  4. Ignoring Versioned Files

Read More