RESTful API for the World. Part 1


The Challenge with RESTful API

There comes a time when you or your organization would like to share data or functionality across departments, trading partners or customers. Usually this entails setting up a system handling request or file drops processing inbound or outbound workflows and managing a data contract to those who wish to consume your offerings. These are typical challenges but the industry has adopted patterns and technologies to address these needs, especially with the advent of mobile applications.

Do I need worry to about an API?

Most likely, yes. Even if you are not required to expose your data there will be a time when something or someone is going to require access. This falls into the Service Oriented Architecture (SOA) discussion but it is directly related to your API offerings. Many organizations are experiencing these challenges now with their mobile ecosystem. Organizational leadership and LOB owners know that data is displayed on a website but don’t see an initial problem with displaying that same data elsewhere (hence the mobile app).

The Take Away: At the very least, architect your internal processes and endpoints as services. Doing so will make dovetailing your future API much smoother.

The Technologies

The popularity of RESTful API architectural style has provided a pattern for the transport, HTTP conventions and message-type definitions for those building an API. It is simple, well known, extensible and allows for your choice of content-types to be used. However, many implementations do not follow the pure RESTful style but rather borrows rules and implementations from it. One example you may see is the use of all HTTP verbs to describe an RPC’s action to be taken against the URI’s defined resource (this is referred to as a RESTful API web service).

A good example of a service offered as an API is Open Weather Map’s API. Below is an example of a RESTful API call that gets weather information by a location coordinates.


This translates into: Using the data API version 2.5 GET weather by lat and lon

I would recommend implementing your service as a RESTful API service. It is widely accepted by the development community and is provides a simple pattern and style to build upon.

The Use Case

Let say you run a company that specializes in social cooking and all that goes with it. Lets call it Cooking-R-Us. One of your resources is probably going to be a repository of recipes your organization has gathered and maintained over the years. You would like offer your data to your clients and partners for free or for a small fee or both. This would position your organization as the first to offer such a service in the social cooking realm to the ever growing world of internet devices and cloud computing.

Company XYZ is a maker of digital kitchen devices/mobile cooking apps and would like partner with Cooking-R-Us. They have the user interface but not the data. They discover your organization offers an API that supplies cooking recipes along with your social data dimensions like ratings and trending metrics. Company XYZ sees a huge un-served market with their devices and apps along with your API. This partnership is beneficial for both parties.

Analysis – The Key to Success

Most of the time and effort required to successfully implement an enterprise, partner facing API is spent on analysis and documentation. Since your company is supplying the data you will be defining the requirements and client usage documents detailed below. Lets review the areas individually:

  • API Scope and Feature Set: This details how your API should be used, what data you can expect to get, the context of the data and the type of consumers that would benefit using the data. Defining this area is beneficial for both your organization and those consuming your services.

  • Data Contracts: This is just a technical phrase for defining your data structure (ie. [first name], [last name] fields defined User Info). It is called a contract since it is the agreed upon structure between the two parties. This is an important step and should be treated as a living document throughout the process. Altering this definition can cause major problems with your clients once you have publish it into production.

  • Data Methods: This is just a technical phrase for defining your data queries/actions. You will define what queries and actions will be available to your users.

  • Authentication and Security Protocol: This is a can be very complicated if you need to maintain strict control over your API. At the very least this would be defined from the client’s perspective. Define technically how a consumer of the service will pass/generate credentials or tokens to identify themselves to the user.

  • Message Workflows: This will define how you expect your clients to interact with your service. This may be as simple as defining a synchronous request/response workflow. It could be more complex asynchronous workflow where a request will be made to initiate the process (such as a job) and subsequent calls to determine the status or even a callback by the API server.

  • Internal data mapping specs: Assuming your organization already owns and maintains the data to be exposed, you will need to define how the existing data sets will be mapped to the Data Contracts that is exposed externally. This may include formatting of dates, adding friendly descriptions to system defined strings and flatting out of complex data structures for easier consumption.

  • Application Infrastructure Architecture: This is a bit more involved then the number of VM instance required to service your API. Depending on the nature of the API, your application infrastructure may required to maintain thousands of open/active connection a second and be able to scale without impacting your users. You may need to add caching or require your users to maintain a persisted open connection all of the time (NOTE: persisted connections is used for very high volume API’s like Apple’s Push notification servers).

Documentation – The Key to Adoption

All API’s speak differently, even using industry standards. This is why it is important to develop technical usages documentation for your client’s technical staff. There are web-based tools that will take the code base of your application’s API can generate readable documentation. The more complete the documentation the greater success your organization will have with adoption. Getting systems to integration and talk to one another is a satisfying accomplishment so creating documentation that fosters that vision will increase your sales and adoption rate. Documentation is a usually takes a back seat but with API implementation it is a first class citizen.

Designing and Developing the API

Since it was determined that a RESTful API design should be implemented we will focus this section on the implementation of REST actions. Continuing with the use case started above, Cooking-R-Us offers the following services:

  • Get Recipes By Search:
  • Set Rating By Recipe ID

The Get Recipes By Search will return a list of recipes that match the search string. The URL action representation will be:

[HTTP GET] http://Cooking-R-Us/api/GetRecipesBySearch?query=chicken

This HTTP GET action is calling the service method that accepts a parameter of a search query.

Note: This naming convention is not consistent with pure RESTful API conventions. Verbs are reserved for HTTP METHODS like GET, PUT, POST, DELETE, etc. For simplicity I would recommend just using GET and POST. GET for getting data and POST for submitting data or performing actions. Using the URL to define the action and using query strings for parameters allows for your API methods to be self documenting. RESTful API purists will not recommend this approach.

This will return something like this:

  "Name":"Chicken Soap",
       "Amount":"1 lb"
       "Name":"Chicken Stock",
       "Amount":"1 Qt"
       "Amount":"4 Cups, Cubed"

User Management and Application Management

Your organization may look at a user being an individual client. In the use case above, Cooking-R-Us has clients that have multiple uses for the API. They have digital kitchen devices and mobile apps that use Cooking-R-Us’s API. So you are going to what to allow the client to have multiple application instances of the API. This allows for greater control of the API where clients can have multiple instance for different environments, devices/applications or all of the above.

Metering Usage

Since Cooking-R-Us is expecting to monetize this offering it is also a good idea to implement some sort of metering of the API. This can be accomplished many different ways. The simplest way is to meter API request count over time resetting after a period of time. Keeping a log of your client’s application request will allow you to monetize and police your API usage.

What’s Next

Well, we talked about the business case, the required analysis, the technologies and the basic implementation of an API. My next article will review a complete technical implementation of a .NET MVC WebAPI starter project called WebAPISoup.

Posted in .NET, IoT, JSON, RESTful, SOA, WebApi and tagged , , , , .