Reading Time: 7 minutes
guest_post

This post is brought to you by Pablo Cibraro. Pablo is a Software Architect focused on MuleSoft’s solutions for Microsoft.

As part of our on-going effort to make Anypoint Platform even more accessible and intuitive for .NET developers, we are thrilled to introduce a RAML parser and Visual Studio extensions that make it easy to consume and implement APIs using RAML.

What is RAML?

latest report
Learn why we are the Leaders in API management and iPaaS
Read reports

RESTful API Modeling Language (RAML) is a language for describing a Web API in terms of resources, methods and implemented patterns (security, paging, filtering, projections, etc). RAML is based on YAML and leverages other open standards such as JSON or XML to document the schema of the resource representations. In short, RAML allows you to do the following for your API:

  • Write Human-readable documentation using Markdown
  • Define supported resources and HTTP methods
  • Reuse common usage patterns such as data paging or filtering
  • Describe expected responses for multiple media types with schemas and examples for each
  • Define security aspects

Here’s an example of a RAML document describing a very simple API for browsing a movie catalog:

This RAML defines a resource “/Movies” to represent a list of available movies in a catalog. It also defines the expected response status codes with the corresponding schema and examples: 200 (OK) for a valid request, and 400 (bad request) for an invalid request.

RAML parser

RAML parser reuses the existing JavaScript parser implementation via a strongly-typed wrapper that provides access to the object model representing the RAML abstract syntax tree (AST), and Edge.js is used as a bridge between .NET and Javascript.

The following code shows how the parser is used to load an existing RAML document:

class Program

{
    static void Main(string[] args)
    {
        var parser = new RamlParser();
        var task = parser.LoadAsync("box.raml").ContinueWith(t =>
            {
                var document = t.Result;
                foreach(var resource in document.Resources)
                {
                    Console.WriteLine("Resource:" + resource.RelativeUri);
                    foreach(var method in resource.Methods)
                    {
                        Console.WriteLine("\t" + method.Verb);
                    }
                }
            });

        task.Wait();

        Console.WriteLine("Press enter to exit..");
        Console.ReadLine();
    }
}

The parser is available in Nuget (raml-dotnet-parser) and the source code is available at https://github.com/raml-org/raml-dotnet-parser.

Client generation in Visual Studio

From Visual Studio, once .NET developers add a reference to a RAML definition, a strongly-typed client proxy will be generated in the project. This proxy internally references a ASP.NET Web API HttpClient class to make the underline calls to the Web API. Therefore, a developer can still use the available extensions and methods available in HttpClient. The proxy will also include the model classes inferred from the JSON schemas exposed in the RAML definition. This process is similar to the “Add Service Reference” command for SOAP and OData service, but the main difference is that the generated code is just a wrapper on top of HttpClient calls.

ASP.NET Web API implementation in Visual Studio

From Visual Studio, you now also have the ability to generate a complete ASP.NET Web API implementation from scratch using a RAML definition. The implementation includes controller classes and route registrations that map exactly to the resources exposed in the RAML definition and model classes for their representation. The model classes are generated from the available JSON schemas. For old school developers, this approach is very similar to writing contract-first SOAP services with WCF. The tool represents a contract as a .NET interface, and the Web API controller is the implementation. This allows simple non-destructive forward-engineering of the code when the RAML contract is changed.

For more information about these tools, check out:

More on the author

Pablo is an internationally recognized expert with over 12 years of experience in designing and implementing large distributed systems with Microsoft technologies and a Connected System MVP. For the last 9 years Pablo has helped numerous Microsoft teams develop tools and frameworks for building service-oriented applications with Web Services and Windows Communication Foundation (WCF). He now focuses on technologies that enable developers to build large scale systems and web applications with focus on mobile, such as HTML5, Node.js, ASP.NET or Windows Azure.