For .net api developers, the WebApi framework offers a compelling alternative to asp.net mvc for slinging json or (gasp) xml over http. One great feature you get out of the box is content negotiation, where WebApi will look at request headers to decide which format to use when processing a request body or sending back a response.
WebApi also includes the concept of an ApiExplorer, a built in service that knows about all the routes, templates and parameters an application is configured to handle. It even supports attaching human friendly documentation.
With these built in perks, WebApi gets you 95% of the way there. What it doesn’t do out of the box, unfortunately, is something that it says right on the box. It doesn’t do web.
HTTP, ReST and the Web
Writing an application that speaks json over http does not automatically give you something that can be called ReST. To get to ReST nirvana your api needs to speak using hypermedia, providing the client with not just data, but links and forms that can do stuff with the data.
If you aren’t familiar with this distinction, here are some great resources:
- Richardson Maturity Model
- Building Hypermedia APIs with HTML (talk by Jon Moore)
- Slide decks by Stefan Tilkov
- Exist In the Web - Not on it slide deck by Amy Palamountain
Jon Moore’s work is particularly intriguing because he shows what you can already do with Microdata.
Microdata boils down to 3 attributes that you stick on elements in your html5 markup, and they’re all you need to give semantic information to a client. You can nest properties into a scope, describe the type of data being represented, and even nest scopes with scopes recursively.
Jon’s talks show how a web client that speaks Microdata can already start on sites like ebay.com, submit a form and find and manipulate resources without knowing anything ahead of time about what resources are there and what URLs are used to access them.
WebApi + Microdata
On the one hand we have a .net framework for writing HTTP apis that has pluggable support for different content types. On the other hand we have html5 and Microdata. Think they could be friends?
When you install this package into your WebApi project, it adds two features.
First, if you enter the URL for one of your api methods into a web browser, you get (relatively) nice, human friendly html5 instead of the wall of xml you would otherwise be greeted with.
Second, and perhaps more importantly, if you browse to ~/api, you will be greeted by an html5 page that includes links and forms for all the routes that are registered with ApiExplorer.
Turn on xml documentation for your project, rebuild, and now all the documentation comments you attach to your controllers and actions appear on the forms.
Why it Matters
Obviously, getting a free html form generated for each action can be a productivity boon for developers who are tired of writing
curl -X POST -H 'Accept: application/json' \ --data 'param1=value1¶m2=value2' \ http://localhost:49497/api/users/fred'
But it’s more than that. Make your client project use html5 and instead of hard-coding URLs for each thing the client wants to do, the client starts at /api, finds the form it wants, fills it in and submits it. The Microdata attributes in the response, along with links and forms, give the client the pieces it needs to drive state, just like Roy T. Fielding intended when ReST was first described.
Do you have third party developers who consume your api? Now you
don’t have to give them a separate document or website
that describes (out of band) how to use your api. Just
link them to
yourwebsite/api, and they can read the
documentation and discover what they can do without
guessing or following brittle conventions.
Putting the web into WebApi removes the tight coupling
between client and server. Now you can change your routes,
rename parameters, add parameters, and the client will
automatically see those changes reflected in the forms
and links they get when they enter your api. No more
/api/v23/users. No more api version headers.
HtmlMicrodataFormatter is pretty young and there are many ideas left to flesh out. For example, making it easy to add links and forms to the output of controller actions, or improving how xml documentation is collected and converted to html, or making it easier to link from resources to related resources with appropriate rel attributes. The list goes on.
I hope you like HtmlMicrodataFormatter, and if you do, maybe get involved and help improve it by submitting feedback, bug reports, enhancements or pull requests to the GitHub project.
Similar to Jon Moore’s python based microdata client, work has started on a .net dynamic client which I hope to share soon.
Get the source and see examples at https://github.com/themotleyfool/AspNet.WebApi.HtmlMicrodataFormatter.