Last time we finished up our basic API implementation. At that point we were done the tutorial but I figured I’d add some tips and links that could be useful.

Better Unhandled Exception Responses

When your application is running in development mode unhandled exceptions will produce an ASP.Net error page.

Looks really pretty, but this in in a browser…

You may have realized that as an API response this is a mass of HTML and CSS so it isn’t all that consumable. What if we could install our own handler for all unhandled exceptions?

Through ASP.Net Core Middleware we can override the default behavior with our own. My implementation is a class called JsonUnhandledExceptionMiddleware which is heavily borrowed from this StackOverflow post. We simply register the middleware and it handles things from there based on the Accept header and whether we’re running in Development or Production.

Middleware is registered in the Configure method of Startup.cs

Validate Models Automagically

You may have noticed our API simply accepts a Post object from POST or PUT requests and blindly inserts or updates it. Real world APIs will likely need some validation.

You may have noticed earlier that our database modelling generated validation attributes based on properties of the database columns.

The Name property of a Post has inherited the Required (NOT NULL) and max length (VARCHAR(200)) attributes from the database.

In our controller we can validate a model against these attributes using the ModelState.IsValid property. The catch is you have to remember to always do this and then return an appropriate response. What if we could do this in one spot and give a reasonable error message in the response?

We can use ASP.Net Core Filters to do this which are somewhat like Middleware but run in the context of MVC as opposed to the HTTP level. My filter implementation is a class called ValidateModelAttribute and borrowed from a blog post.

We register our filters with the MvcOptions parameter to AddMvc in the ConfigureServices method of Startup.cs

Our filter checks if the ModelState is valid and extracts validation messages to send with an HTTP 400 error if not

API Documentation

Producing documentation for your API can be pretty important. Swashbuckle is a library for ASP.Net Core that can generate OpenAPI documentation from your API controllers. Swashbuckle can pull information about your API through C# documenting comments as well as attributes on your controller methods.

I found the Microsoft tutorial really helpful for getting started with Swashbuckle.

Reverse Proxying

ASP.Net Core applications run on servers called IIS (Windows only) or Kestrel (cross platform). Kestrel is enough to run your API standalone but there can be advantages to putting a traditional web server like Nginx or Apache in front of it as a reverse proxy. These servers can handle HTTPS termination as well as implement compression and other features for your API.

Microsoft has tutorials for reverse proxying using Nginx or Apache.

Deployment

At some point you’ll probably have to build and deploy your API for non-development usage. I simply use the Visual Studio publish feature to publish to my Ubuntu server over SFTP. Alternatively you can deploy the application package locally and use another method like SCP to get it where it needs to go.

If you’re hosting on Windows or Azure you may be able to use Visual Studio’s Web Deploy but I have less experience in that area.

Conclusion

Thanks for reading! The source for for this part is available on GitHub.