According to Richardson Maturity Model, REST API level 3 should provide hypermedia within responses as metadata, so that users can easily navigate to other resources. This is particularly important if Microservices architecture (MSA) is considered for your service or application. Because MSA is a collection of small REST API services, each API server should provide complete set of documents or manuals for others to consume it properly. In order to provide document automation, Swagger is one of the best choices, and HAL, in order to provide hypermedia within the response, is also yet another option. Of course, consuming those REST API at client applications is also important. In this case, AutoRest can give great benefits for your development. In this post, I’ll discuss HAL, Swagger and AutoRest with some demo code.

Integrating HAL

HAL (Hypertext Application Language) has been suggested by Mike Kelly. Its formal specification can be found at this IETF draft. Generally speaking, many REST API services are well structured. They don’t just only return data in the response, but also include various metadata for reference purpose, in their own way. HAL offers a standardised way of including hyperlinks into those responses. Here’s an example

If you send a request with the URL above, the expecting response will look like:

However, if HAL is applied, the response will look like:

Let’s see another example returning a collection.

The request will expect response like:

If HAL is applied, the response will look like:

Can you see differences? HAL applied responses contain much richer data that can easily navigate to other resources.

OK, theory is done. Let’s implement HAL on your API. First of all, assuming you’ve got an existing Web API app containing models of Product and ProductCollection looking like:

There are many HAL implementations on our NuGet. For now, I’m going to use WebApi.Hal. Once installed, you can modify those models with this way, by minimising impacts on the existing application:

Then, register HAL into your Global.asax.cs or Startup.cs:

That’s it! Too simple? Here’s the magic inside the Representation class. It has the public Links property that takes care of all hypertext links. All we need after the HAL implementation is to add appropriate links to each instance, manually or automatically. Here’s a way to include hyperlinks manually within a controller level:

Once it’s done, build it and check the API response. Then you’ll see the result including those HAL links like above. Now, let’s move to the next part, Swagger.

Integrating Swagger

According to Swagger website, Swagger provides a standard, language-independent interface to REST API so that both humans and computers can easily find and understand the API structure without reading source codes or documents. There are several other alternatives like RAML or API Blueprint, so it’s up to you which one should you choose.

Swashbuckle is one of C# implementations of Swagger. It’s easy to use and virtually zero configuration is required for the basic usage. Let’s install Swashbuckle into your project. Once installed, it also adds another file, SwaggerConfig.cs under the App_Start directory. You can directly use it or do some modification for your application. Let’s have a look.

When you open SwaggerConfig.cs file, it looks like above. In order for you to have more control on it, comment out the first line, [assembly: ...] and make the Register() method to be an extension method:

Then, put the following like into either your Global.asax.cs or Startup.cs for registration:

That’s all. Build and run your app, type URL like http://my.api.service/swagger and you will see the Swagger UI screen like:

What you need to notice is the JSON schema URL in the picture above. When you type the URL from Postman, it will look like:

This is basically a JSON schema file and pretty much equivalent to WSDL from SOAP. With terms of WCF, it contains both service contract and data contract so, with this schema, your client applications can access to the API and consume it. There’s no obstacle for it.

So far, we’ve implemented both HAL and Swagger on your REST API server. How can we then consume those APIs on your clients like web app or mobile app? Let’s move onto the next section for this.

Deserialising Swagger JSON schema with AutoRest

Once Swagger JSON schema is generated, your client apps should be able to consume it with minimised efforts. AutoRest can bring great benefits to your client apps. It automatically generates both service contracts and data contracts pointing to your REST APIs using Swagger JSON schema. Currently, AutoRest supports C#, Java, Node.js and Ruby and the number of languages gets gradually expanded.

Here’s an ASP.NET MVC app. Within the app, assuming there’s a folder, Proxies. Swagger JSON schema file is then placed into that folder with name of swagger.json. Then install AutoRest CLI app and runtime library from NuGet. In order to auto-generate client libraries, try the following command on your Command Prompt:

What does the command line mean? Here’s the brief explanation:

  1. Run AutoRest.exe
  2. Input JSON schema name is swagger.json
  3. The namespace for auto-generated files is HalSwaggerSample.WebApp.Proxies
  4. Store auto-generated files into Proxies
  5. Set output file type as C#

After the generation, you will be able to see bunch of files have been stored into the Proxies folder. The most important file is HalSwaggerSampleHalApiApp.cs. Of course, the file name (or class name) will be different from yours. It provides the service endpoint and service contract information. It also contains the corresponding interface, IHalSwaggerSampleHalApiApp, so this service contract is testable, mockable and injectable. Therefore, your controller/action can be written like:

Therefore, the result screen will look like:

Did you find that can’t be easier?

We’ve so far had a look at HAL, Swagger and AutoRest. Both HAL and Swagger are to design your REST API to be more discoverable, readable and maintainable and make client apps build their access point much easier with tools like AutoRest. How about implementing those into your Web API, if you’re considering MSA? Kloud can help you.

The entire sample source code that I wrote for this post can be found at here.

, , , ,

Join the conversation! 10 Comments

  1. […] This is a cross-posting over Creating Service Contract with AutoRest, Swagger and HAL at Kloud […]

  2. Great article! Thanks for your sharing.

  3. For the installation of both HAL and Swashbuckle, you mention setup in either the global.asax, or in startup.cs. Unfortunately, in my ASP.NET Core sample project, I cannot figure out how to make appropriate adjustments in startup.cs. Can you post an example of the mods necessary for startup.cs?

  4. Hmmm. I’m having problems with this setup in C#. In the generated JSON schema, the “_links” property of any models deriving Representation is of type “array”. The generated AutoRest client then expects to receive a collection. However, in the actual response returned by the service the “_links” is an object, not an array, as dictated by HAL spec. This causes an error when the client tries to deserialize the JSON – it cannot deserialize the object it received into the collection it expected. This is essentially the same problem than in the open issue #71 of WebApi.HAL:

    Did I miss some step where I can configure the schema to be configured differently?

    • @Pete Hmmm… That’s interesting. It doesn’t seem to be an issue on WebApi.Hal. Have you modified your swagger.json schema output by applying the SchemaFilter option at your SwaggerConfig.cs ? This would be helpful:

      • It must be something simple I’m missing. I can see similar code that’s causing problems to me in the sample, and the sample is a working example.

        In the sample repository, there is the AutoRest generated Product class in namespace HalSwaggerSample.WebApp.Proxies.Models. It has a property IList LowLinelinks.

        In the issue I’m having, the JSON

        “_links”: {
        “self”: { “href”: “/products/5” },
        “find”: { “href”: “/products/{productId}”, “templated”: true },
        “collection”: { “href”: “/products” }

        cannot be deserialized into IList. The JSON represents an object, the LowLinelinks property is a collection. The JSON deserializer throws an exception.

        And yet clearly your sample works. I must be doing something wrong. I’ll examine the sample more deeply to see what it’s doing.

      • I think I figured it out. My service only knows how to return the HAL-ified JSON, when it should only do that if the requested content type indicates the client specifically requested that. For plain “application/json” I need to return “regular” JSON – which is not what I’m currently doing. That’s why the sample works and my project does not. Allrighty, to work fixing this, then.

        Thanks for the blog post, it’s been helpful!

      • @Pete I’m happy to hear that you’ve sorted out the issue! Thanks for visiting my post.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: