Just-Eat spectrum-bottom spectrum-top facebook google-plus instagram linkedIn pinterest reddit rss twitter_like twitter_reply twitter_share twitter_veriviedtwitter vimeo whatsapp youtube error_filled error file info-filled info loading star tick arrow arrowLeft arrowRight close download minus-filled minus move play plus-filled plus searchIcon settings

Tag : OpenRasta

682 views

OpenSourced: OpenRasta Middleware

OpenRasta meet OWIN

We are at it again. Previously we brought you OpenRastaSwagger allow you to have shiny documentation for your APIs. Now we wanted to contribute something to the community that would get you excited again as an OpenRasta developer or someone looking for an alternative to the WebAPI world.

Enter OpenRasta.Owin – a Middleware package for the OpenRasta framework allowing you to host your APIs in Katana on the OWIN Specification.

Why have we created this?

Today we’re working in the OpenRasta community which has served us well – after all, we’ve accomplished great things. But as always many minds are always better and, by joining forces with the OWIN Middleware community, we open a whole new world of options to our solution and yours. The Middleware community has exploded recently and will continue to do so with the introduction of vNext, which is hosted on Owin/Katana by default.

nuget.org search: ‘Search for OWIN returned 478 packages’

‘How do I move’ We hear you say.

The move can be as easy as three steps…

  1. Remove your current OpenRasta hosting.

remove AspNet Hosting

  1. Add OpenRasta.Owin hosting Middleware.

Add OpenRasta.Owin

  1. Create the magic Startup.cs with the following code. The key feature that the OpenRasta.Owin package brings you is the UseOpenRasta Middleware extension.

If your project is a little more complicated and you need to specify your own dependency resolver that’s also fine. You can specify the dependency as the second parameter.

I need more from this Package!!

No one is perfect and, despite our best efforts, this package might not meet everyone’s expectations. But don’t worry – there is light at the end of the tunnel. The light is you…. Yes, you can contribute or even fork it and make it your own. Take a look at the licence on GitHub for peace of mind.

Downloads

Source code is available on GitHub here:
//github.com/justeat/openrasta-hosting-owin

NuGet packages available here:
//www.nuget.org/packages/OpenRasta.Owin

670 views

OpenSourced: OpenRastaSwagger

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: //github.com/justeat/OpenRastaSwagger

NuGet packages available here: //www.nuget.org/packages/OpenRastaSwagger/