OpenRasta and JUST EAT
We’ve previously talked about how we build on a lot of open source at JUST EAT – so today we want to give a little back and publish some of our extensions to a C# project called OpenRasta.
OpenRasta is an open source, C#, Resource-Oriented framework that you can use to build MVC-style frameworks and RESTful APIs. For the past couple of years, we’ve used it to power many of our internal web-APIs.
We have a handful of different C# web frameworks in production (OpenRasta, ServiceStack, NancyFx and ASP.NET MVC), all serving different purposes. Regardless of the framework we’ve chosen for a particular task, there’s one constant when we’re building web-APIs – the need for accurate, human-readable documentation.
But first… a brief history of documenting RESTful APIs
Documenting RESTful APIs is a challenge – predictable API structures were lost as the industry transitioned away from SOAP web-services, with the closest attempt at a verifiable spec for REST emerging as WADL. WADL was submitted for to the W3C in 2009, but there are currently no active plans to standardise it and it has never reached widespread adoption.
WADL was widely criticised during its gestation in 2007-2008 for a variety of reasons. It’s focus on client generation drew ire from the RESTful community who drew parallels to the negative points of WSDLs in WS-* APIs, they considered the specification too broad to be useful, and the belief that RESTful APIs should be self describing using HTTP’s semantics undermined adoption.
With WADL effectively dead, in early 2010 a company called wordnik started developing the spec that became known as swagger to document their APIs in a language agnostic way. Instead of designing a spec to support compile-time code-generation like WADL, swagger put the focus on generating usable and human readable documentation.
Swagger managed to hit the sweet spot in the middle – it provided useful tooling in the swagger-ui that wasn’t taxing to implement, without forcing SOAP-like designs onto RESTful APIs. It doesn’t support everything – versioning is notably absent – but it’s good enough to be useful.
Documenting our OpenRasta APIs
We haven’t been flying blind – over the past few years, we’d put together our own “json spec” for documenting RESTful APIs that worked well for us – it was the way we dealt with communicating API requirements between teams – but we’d never invested the time in building tooling as sophisticated as the swagger-ui.
In late 2013, we started building an API using ServiceStack and we found that the out-of-the-box swagger-ui plugin proved really productive, and gave us a great way to demo and interact with a headless API. Because there’s no “one framework to rule them all” we wanted to get the same awesome UI and manual feedback cycle from some of the other frameworks we use.
The first target was OpenRasta, so in our first hackathon of 2014 a couple of our devs started digging through the OpenRasta source code and worked out how to plug in some OpenRasta Handlers (similar to the Controllers in other MVC frameworks). These handlers use a combination of the OpenRasta meta-model and reflection to emit swagger 1.2 formatted json that described the other handlers in the application.
We’ve added a couple of things – extra attributes to let you drop notes into the generated swagger documentation, and attributes to help you hint at types that we can’t discover by reflection (notably, handler methods that return OperationResult(xyz) must be annotated for return types to be correctly identified). We’ve started to roll these things out across our internal APIs and we’re pleased with the results.
Downloads
The OpenRasta project is a fairly quiet at the moment, so we’re releasing this as a stand-alone assembly and NuGet package that targets the last stable available version of OpenRasta (2.1).
Source code is available on GitHub here: https://github.com/justeat/OpenRastaSwagger
NuGet packages available here: https://www.nuget.org/packages/OpenRastaSwagger/
Comments are closed.