Minding the API Hierarchy of Needs with RAML and APIkit
The popularity of APIs is rapidly changing the way we do business by stimulating innovation and new developer ecosystems around traditional enterprise business models. APIs have achieved what the SOA vision promised by providing managed access to data and business logic through simple interfaces.
APIs allow the capabilities of an underlying application to be freed from the constraints of a pre-defined user interface, and make them available for use by other applications to provide yet bigger and better services with almost unbounded flexibility.
One has only to look at ProgrammableWeb.com’s rapidly-growing catalog of over 10,000 public APIs to appreciate their importance in today’s world. Let’s look at a few API examples to see how companies are using them to drive innovation.
Amazon provides a foundation for building technology platforms by exposing not just a management web console but also a comprehensive API for each offering. This allows Amazon’s services to be easily repackaged and integrated into customer solutions. Likewise, Salesforce processes the majority of its transactions not through its web UI but through their API. By allowing simple access to the underlying CRM data, Salesforce can be easily integrated into a customer’s own enterprise solutions.
As interesting as the Amazon and Salesforce API examples are, they only represent the tip of the proverbial iceberg of all enterprise APIs in existence. Rather, the majority of APIs in today’s enterprises are either only meant for the consumption of a subset of internal users within the company, or meant for a specific set of partners.
The trend for the approach used in designing and building public APIs is towards a RESTful approach, and away from the SOAP web services approach, as shown by the following graph drawn from the directory of APIs within ProgrammableWeb.com. This trend also extends to the internal and partner APIs within the enterprise.
Figure 1 – Number of SOAP vs. REST based APIs (Source: programmableweb.com)
However, as strong as this trend has been, there has not been a comprehensive solution for addressing all the needs of RESTful API stakeholders. Indeed, if one were to build an API hierarchy of needs in a similar fashion to the famous Maslow's hierarchy, the associated pyramid would look like the one below.
In other words: you need to make sure that your APIs will actually fulfill their intended purpose; if so, you need to implement them efficiently and maintainably; once that’s done, make sure you can engage their users so they do, indeed, get used; and if you’ve done all that, you have something valuable to manage and monitor. As in Maslow’s hierarchy, it’s tempting to shortcut your way to the top, to skip the main meal and go for the dessert, but heed your mom’s advice: it’s not a healthy approach. In the rest of this article, we will take the healthier path and focus on the two most fundamental enterprise API needs of API design and API implementation, and show how the RESTful API Modeling Language (RAML) and its tools along with APIkit can address these needs.
API Design with RAML
For a RESTful API, its design encompasses its set of resource names, their hierarchy, their associated methods, parameters, request and response bodies (entity representations) and response codes. This design forms the contract upon which developers build applications. An optimal API design should enable application developers to easily understand the purpose and usage of the API so that they can quickly become productive with it. The API’s design should also be optimized for its intended application types. A mobile application, for example, will place different constraints on an API than a web application, with the mobile application being much more sensitive to the number of calls and the size of the data being returned by the API’s methods.
To get to an optimal API design, therefore, API developers need to iteratively define the structure of the API in an expressive manner, and to review it with their target application developers so that they can assess its usability and fit for the applications that they want to develop. Enter the RESTful API Modeling Language (RAML). As described on RAML.org, RAML “is a simple and succinct way of describing practically-RESTful APIs. It encourages reuse, enables discovery and pattern-sharing.”
Besides making it possible for developers to express the design of their API, one of the important benefits of RAML is that it already has, despite its relatively recent introduction, a number of open source projects that are designed to facilitate good API design. One of the most important such projects is the API Designer, which provides an editor for drafting the API’s structure using RAML while rendering in real time an interactive console to enable interaction with the API.
Figure 2 - Screen Shot of API Designer
Using RAML and the API Designer, API developers can apply an API-first design approach: that is, they can draft the design of an API in RAML using the API Designer’s editor and at the same time share the design with potential application developers of the API, either by sharing the RAML document itself, or by sharing its automatically-generated interactive console. In fact, the API Designer is integrated with a mocking service that allows auto-generation of a mocked implementation of the API given its RAML spec. The mocked service can be accessed by the interactive console, other RAML tools such as the API Notebook, or even mobile apps that may be in their own design cycle -- which can now proceed in parallel with the API design cycle. This optimizes for an iterative feedback loop to get to a clean and easy to use API for its intended users before investing in its implementation.
When the design of the API is complete, its implementation can be performed in any language or framework, as per the API developer’s preferences and needs. There’s a growing number of open source projects that simplify the implementation of an API starting from its RAML definition. These projects include a JAX-RS stub generation tool for RAML, as well as APIkit, which is an open source project, contributed by MuleSoft, for the implementation of a RAML-defined API using Mule flows. Let us take a closer look at APIkit to see how it helps satisfy the second category of “API implementation” within the API hierarchy of needs.
API Implementation with APIkit
An API’s implementation often consists of a mix of new business logic as well as connectivity and integration logic. Often times, the connectivity and integration logic needed is beyond trivial and as such its implementation requires complex custom code. In such cases, the implementation of the API through Mule flows, rather than custom code, becomes of great benefit, as Mule flows allow API developers to take advantage of all of the MuleSoft Anypoint Platform’s capabilities to deliver the API.
These capabilities include advanced message processing (e.g. splitting and joining the pieces of a message), complex data transformations, and simplified robust connectivity to hundreds of SaaS and on-premises applications endpoints such as Salesforce, SAP, or Microsoft Dynamics as well as heterogeneous protocols such as FTP/S, MQ, JMS, or AMQP.
APIkit is an open-source project that greatly simplifies the development of RAML-defined APIs with Mule flows. The project consists of Maven- and Eclipse-based tooling which can be used from MuleSoft’s Anypoint Studio IDE. For starters, one can create a new Mule project from a RAML API definition, which will automatically generate and associate an integration flow with each resource/method pairing defined within the RAML spec.
Figure 3 - APIkit Project within Anypoint Studio
APIkit generated Mule flows come with a default implementation that returns the example responses within the RAML API definition, thus allowing the project to act right away as a mock implementation for the API. This capability allows developers to have a working, mocked, version of the logic behind the complete API and to iteratively implement the actual integration logic needed for each resource/method pair using Mule constructs.
Developers can also take advantage of all of the capabilities of Anypoint Studio such as the Visual Flow Debugger or the Anypoint DataMapper for the implementation of advanced data transformations. APIkit also allows for incoming API requests to be routed to existing Mule flows (as opposed to having to generate new flows from scratch) as well as the ability to easily map Java and Mule exceptions to HTTP response codes that need to be returned by the API.
Finally, APIkit projects come packaged with a pre-defined interaction console that is exactly the same as the one included (and dynamically rendered) within the API Designer tool. The console allows API and application developers to easily interact with the API as well as browse its RAML embedded documentation.
When the API developer has completed the API implementation, the API can be deployed to the MuleSoft Anypoint Platform either on an on-premises Mule ESB instance or to a cloud based environment on MuleSoft’s iPaaS offering, CloudHub.
In this article, we showed how the REST API Modeling Language (RAML) and some of its open source projects, namely API Designer and APIkit, can be used to satisfy the two most fundamental needs of API design and API implementation within the API hierarchy of needs.
About the Author
Reza Shafii is Director of Product Management at MuleSoft, provider of the world’s most widely used integration platform.
A Guide to REST and API DesignCA Technologies
Chris Richardson Oct 09, 2015