HTTP API Problem Details in ASP.NET Core

Problem Details in ASP.NET CoreIf you’ve been writing HTTP API’s, you likely have needed to return exceptions and errors back to the consuming clients.  Before you go and grow your own solution to this common problem, there is RFC 7807 Problem Details for HTTP APIs which set out solve this problem.

“problem detail” as a way to carry machine-readable details of errors in a HTTP response to avoid the need to define new error response formats for HTTP APIs.

Problem Details in ASP.NET Core

Now that you’re on board with Problem Details, how do we use or implement this in ASP.NET Core.  Thankfully, Kristian Hellang has done all the heavy lifting and released Hellang.Middleware.ProblemDetails on NuGet.

Hellang.Middleware.ProblemDetails

Once you get the NuGet package, it’s simply a matter of adding it to your Startup’s Configure(IApplicationBuilder app):

By default with no configuration, this will return a Problem Details body and application/problem+json content type for status codes returned from MVC. This means 404’s as well as status codes you return from your controller actions explicitly.

Here’s an example of the response for a 404 when a route is not found.

For making explicit returns such as UnauthorizedResult:

This returns, as you might expect:

Bad Request

Most often you might be return a BadRequestObjectResult when the users sends malformed request.  In this case the solution is pretty sweet.  Simply provide BadRequest() with an object that is or derives from Microsoft.AspNetCore.Mvc.ProblemDetails

ProblemDetailsException

Another option is throw an exception.  Specifically you can throw a ProblemDetailsException that takes a ProblemDetails as a parameter.

Mapping Exceptions to ProblemDetails

Although I’m not in love with throwing a ProblemDetailsException, one of the reasons is you may not be directly inside an MVC Controller action.  If you follow my blog enough, you know I like to decouple using something like the MediatR library.  In this case you likely won’t be throwing a ProblemDetailsException.

But no worries, this situation is covered by being able to map exceptions to ProblemDetailsExceptions in the configuration.

IncludeExceptionDetails

If a 500 occurs due to an unhandled exception, this is covered.  However you likely want to see the exception details when in development.  Again, no problem!

Sample

This post really revolves around the sample on the GitHub repo.  Check it out to try it out yourself.

Are you using another solution for ProblemDetails in your HTTP API’s?  Let me know in the comments or on Twitter.

Enjoy this post? Subscribe!

Subscribe to our weekly Newsletter and stay tuned.

RESTful JSON: Adding Links to your APIs

RESTful JSONThere’s a new media type available, RESTful JSON, that was recently registered (Feb 1st 2018) with IANA.  It’s really the simplest possible media type to use in order to start adding links to your JSON APIs.  The new media type is application/vnd.restful+json 

Adding Hyperlinks

The simplicity here is that you can start using this media type with existing APIs to start adding links to your existing objects.

  1. JSON objects MAY include a url property to indicate a link to itself
  2. JSON objects MAY append _url to properties to indicate related links

Example

Here’s an existing payload of a e-commerce shopping cart.  It has one product in the cart.

Now we are going to add a couple links.  We are going to add a link to the product in our cart to the product page, and add another link to provide the URI for the checkout page.

Runtime

Links are to be used at runtime by your client.  Meaning the presents or absence of them will determine how your client behaves.  With links provided in the API, you can now traverse the payload at runtime rather than hardcode URIs.

Are you using a hypermedia content type?  I’d love to hear your comments or on Twitter.

Enjoy this post? Subscribe!

Subscribe to our weekly Newsletter and stay tuned.

Self Descriptive HTTP API in ASP.NET Core: Hypermedia Clients

This post is in my Self Descriptive HTTP API in ASP.NET Core series. It demonstrates how to design an HTTP API like a regular HTML website. This specific posts covers hypermedia clients.

If you’re new to this series, here are earlier posts to get up to speed:

If you have any questions, please follow me on Twitter.

Hypermedia Clients

My perception is that most people new to hypermedia driven APIs think that consuming hypermedia happens via a magic library.

Or via some code generation that ultimately gives you a client library that understands every endpoint.

I’m not sure why this is, possibly the client code gen libraries behind SOAP/WSDL or Swagger/OpenAPI.

In my experience developing and consuming a hypermedia driven API, there is no magic.

Your consuming client needs to understand the content beyond just the media type for a given URI.

In a custom application, you likely want to show the user specific actions within the UI depending on if the link or action is returned in the API payload.

In our Todo application from my HATEOAS post, the action of marking a Todo item as complete was conditional.  It wasn’t available on every Todo item.  My UI would likely reflect that.

The same goes with links to other resources, they may or may not be in the payload.

Siren Browsers

However, you can make a generic UI if you use a defined media type.

Since I’ve been using Siren in my previous examples, we will keep with that for a client examples.

These Siren browsers are no different then HTML browsers.  They understand the media type and render UI.

What this shows is the ability for you to create re-usable components based on the specifics of the payload your server is returning.

In my Todo example, I could create a specific UI component that is used when retrieving a Todo item from the API.

Siren Client Helper Libraries

You technically don’t need any libraries to start consuming a siren payload.  As long as you understand what content inside the siren schema is going to be returned you should be able to deserialize the JSON into your own type and do what you want.

Super Siren is a pretty good example of a Javascript helper library.  It has helpers for making HTTP requests and then performing navigation and actions.

Next

Looking ahead I will start to develop our ASP.NET Core client.

As well as discuss why why URLs become opaque.

Meaning there is no difference between

http://domain/api/todo/123

and

http://domain/cf2b6d63-9a7f-4dc6-9989-f12bb8af7715

If anyone has any other suggestions or recommendations about this series, please leave comment or let me know on twitter.

  1. Building a Self Descriptive HTTP API in ASP.NET Core
  2. Object as Resource
  3. Hypermedia
  4. Siren
  5. HATEOAS
  6. Hypermedia Clients