Fotolia
Best tools and methods for designing RESTful APIs
Approaches to RESTful API design may differ, but five essential elements to API design exist to help guide your tool selection conundrum and solve your RESTful API design problems.
There are two broad pathways to designing RESTful APIs.
One is the open process approach, which is the most common. This approach focuses on steps and tools that support the process of API design, placing few, if any, constraints on the nature of the APIs to generate.
The second is the model approach -- also known as the specification approach -- which starts with a specification and/or model of a RESTful API and supports the adaptation of that model to the specific interface requirements of each project. As APIs become more common, this strategy is gaining ground, but not without its share of complications.
The open process approach
It's fairly easy to turn software architect-created Unified Modeling Language into an API specification, and most of the interactive development environments, such as NetBeans and Eclipse, have tools that facilitate a so-called open process transformation. These tools presume that the basic nature of the API is defined by the component relationships, and the translation of those relationships into the actual APIs is fairly mechanical, especially it's if a single API or a set of closely related APIs within a limited application scope.
The model approach
The goal of the model approach is to create best-practices structures for all RESTful APIs -- and sometimes even for all APIs -- in which the APIs are refined to lend themselves to a specific function. This approach enforces standard ways to do the same thing in different places, which reduces developer confusion and errors, as well as facilitates security and compliance monitoring.
Five elements of API design tools
Both the open process and the model approaches use a multitude of tools to solve problems that result from designing RESTful APIs. These tools tend to address issues of API visualization, API cataloging, API model enforcement, API code generation and API testing. However, it's sometimes difficult to figure out which API design tools address which of these issues.
API visualization is one of the fundamental steps in design, because it frames a graphical view of the API for users and enables users to interact with services that use a type of generalized API GUI. Most interactive development environments have visualization tools available, but these tools only offer basic capabilities. Swagger UI is a popular API visualization example that makes the in/out data structure of an API visible; it also exhibits simulated responses to given API caller requests.
An API catalog is the central element of any API design strategy. Catalogs hold API definitions and make them available to developers. In some cases, catalogs may also drive API management processes, like access control or load balancing. Most API management suites will include a catalog, and separate API catalog tools are available from companies like Swagger, Oracle and IBM, as well as in open source form, like ReDoc. Catalog tools may provide a computer-browsable catalog, a printed API document set or both. Decide what to look for before choosing a specific tool to manage the catalog.
API model enforcement and standardization is at the heart of the model approach to designing RESTful APIs. These types of tools require a structured set of API definitions, using formats like Swagger, API Blueprint or RESTful API Modeling Language (RAML). In this critical element of the model approach to API design, it's best to start with the API definition standards and then jump off to tools that support them. Otherwise, you may end up with a set of tools that don't connect to each other, which would leave gaps that can hinder and defeat the implemented standards on the APIs.
API code generation is helpful to quickly convert a design to implementation without risk of errors. Many of these products are integrated with, or part of, a catalog solution. APIMatic and REST United are examples of code generators, and Swagger also provides a similar API tool in its suite. The big advantage of code generators is their facilitation of rolling changes to software when an API changes.
Testing APIs should always be a part of an API design task and can include API virtualization as a technique. Most API management suites include some level of API testing, and both SmartBear and Runscope offer a range of API testing tools, which include sliding scale pricing depending on scope and features. SmartBear also provides monitoring capability. API monitoring helps keep track of API performance and health with analytics-based tools, like APImetrics.
Tool selection approaches
Certain API management suites have many useful tools for designing RESTful APIs. It's worth looking at MuleSoft's API management tools, as well as IBM's Bluemix, Rogue Wave's Akana and Swagger's suite of API tools. Swagger probably offers the most complete set of API design and validation tools available, so there's nothing wrong with starting a tool review there. Also, review the major cloud providers' API tools; Amazon, Google and Microsoft all offer tools that facilitate the use of their cloud services models, and some can extend to broader enterprise missions.
Secondly, there are open specifications and modeling languages for API design. Swagger's OpenAPI Specification is widely used by API tool vendors, and it's one of the best places to start a search for practical API design tools that work together. RAML and its associated tools present another good way to unify a selection of tools under a common model. If you don't find a management suite that works, adopting the model approach is the next best option for unifying your API design. Visual Paradigm has a nice RESTful design tool that works with several of the specification and modeling products.
Sources like Moesif offer a complete set of API design patterns and best practices, which may be the best approach if you're planning to adopt an open process approach to API design. Try to find design patterns that define a broad RESTful model, and then refine it for various types of APIs, rather than a disconnected set of process-specific design patterns.
In the long run, leaning toward a model-driven or specification-driven approach in API design is probably the best route, especially since APIs aren't going to get simpler in a microservices-driven future. Even if you're committed to the open process approach, try to use models and specifications to evolve your business's API thinking and prepare for the future.
