Saturday, August 16, 2014

API Management for OData Services

The OData protocol is a standard for creating and consuming Data APIs. While REST gives you the freedom of choice to choose how you design your API and the queries you pass to it, OData tends to be a little bit more structured but at the same time more convenient, in terms of exposing data repositories as universally accessible APIs.

However, when it comes to API Management for OData endpoints, there aren’t many good options out there. WSO2 API Manager makes it fairly straightforward for you to manage your OData APIs. In this post, we will looking how manage a WCF Data Service based on the OData protocol using WSO2 API Manager 1.7.0. The endpoint that I have used in this example is accessible at

Open the WSO2 API Publisher by visiting https://localhost:9443/publisher on your browser. Login with your credentials and click on Add to create a new API. Set the name as northwind, the context as /northwind and the version as 3.0.0 as seen below. Once done, click on the Implement button towards the bottom of your screen. Then click Yes to create a wildcard resource entry and click on Implement again.

Please note that instead of creating a wildcard resource here, you can specify some valid resources. I have explained this towards the end of this post.

In the next step, specify the Production Endpoint as and click Manage. Finally, select Unlimited from the Tier Availability list box, and click Save and Publish. Once done, you should find your API created.

Now Open the WSO2 API Store by visiting https://localhost:9443/store on your browser, where you should find the northwind API we just created. Make sure you are logged in and click on the name of the northwind API, which should bring you to a screen as seen below.

You now need to click on the Subscribe button, which will then take you to the Subscriptions page. In here, you need to click on the Generate button to create an access token. If everything went well, your screen should look something similar to what you find below. Take special note of the access token. Moving forward, you will need to make a copy of this to your clipboard.

The next step is to try the API. You have several choices here. The most convinient way is to use the RESTClient tool which comes with the product. You simply need to select RESTClient from the Tools menu on the top. To use this tool, simply set the URL as http://localhost:8280/northwind/3.0.0/Customers('ALFKI')/ContactName/$value and the Headers as Authorization:Bearer TOKEN. Remember to replace TOKEN with the access token you got from the step above. Once you click Send, you should see something similar to the screenshot below.

Another easy option is to use curl. You can install curl on most machines and it is a very straightforward command line tool. After having installed curl, run the following command in your command line interface:
curl -H "Authorization:Bearer TOKEN" -X GET "http://localhost:8280/northwind/3.0.0/Customers('ALFKI')/ContactName/$value"
Remember to replace TOKEN with the access token you got from the step above.

For more challenging queries, please read through Microsoft’s guidelines on Accessing Data Service Resources (WCF Data Services). Remember to replace with http://localhost:8280/northwind/3.0.0 in every example you find. For the RESTClient, note that you will have to replace " " with "%20" for things to work. Also, for curl note that on some command line interfaces such as the Terminal in your Mac OS X, you might have to replace "$" with "\$" and " " with "%20" for things to work.

In the very first step, note that we used wildcard resource. Instead of that, you can specify some resources to control what types of access is possible. For example, in the list of queries mentioned in the link above, if you want to allow the queries related to Customers but not the ones related to Orders, you can setup a restriction as follows.

Open the WSO2 API Publisher by visiting https://localhost:9443/publisher on your browser. First click on the northwind API and then click the Edit link. Now at the very bottom of your screen, in the Resources section, set URL Pattern to /Customers* and Resource Name to /default. Then click Add New Resource. After having this done, click on the delete icon in front of all the contexts marked /*. If everything went well your screen should look similar to the following.

Finally, click on the Save button. Now, retry some of the queries. You should find the queries related to Customers working well but the queries related to Orders failing unlike before. This is a very simple example on how to make use of these resources. More information can be found in here.

Please read the WSO2 API Manager Documentation to learn more on managing OData Services and also other types of endpoints.

Sunday, August 3, 2014

The right Governance Tools are key to the right Level of Maturity

Governance is part and parcel of any enterprise of the modern world. Knowingly or unknowingly, every single employee is a part of some form of corporate governance. Having the right tools and frameworks not only helps but also ensures that you design, develop and implement the best governance strategies for your organisation.

The types of tools and the approach required for governance varies significantly depending on the level of maturity of an organisation. The Capability Maturity Model Integration programme explains several levels of maturity an organisational process can be in. It is ideal for all organisations to eventually reach the optimum state in terms of all its processes, but it is not always required and can also be very expensive if over done.

The key to understanding what level of governance is needed is to find where your organisation is in terms of its level of maturity. And, you may choose different types of governance products for different types of process requirements. When selecting right tool or framework, you should not only focus on what the product is capable of and how much it costs, but also what types of metrics can they provide for you to iteratively improve the maturity of your organisation.

A basic registry/repository solution that can be used to capture requirements, group them into projects and provide some analytics around what they provide can only help you get past the second level of maturity. Similarly, the most advanced deployment composed of multiple products of multiple vendors in combination of a series of home-grown solutions, will not only burn a lot of your finances but also will end up taking a lot of time on establishing and maintaining these processes.

It takes a lot of thinking and planning, and the right mix of products as well as expertise will be required. To open doors for the next level of maturity, your company will need the right governance solution that is unique to your requirements. Most of the work done and organisational transformation happens within the third level of maturity and the journey beyond is not so difficult. But, this what requires proper understanding and planning. And, making the right choice of toolset will be pivotal towards taking your organisation to the most optimum level of maturity.

Therefore, it is crucial that you pay attention to requirements of later stages early enough to help you invest the right amount of time and money before starting to take your organisation to the next level of success.