How API Description Languages Enable API IDEs

API description languages are a new category of programming languages for software developers that are used for building applications that make APIs available to share data or functionality. They are often associated with RESTful APIs that share information over the Web. RESTful APIs are used by Twitter, Google, the U.S. government, and many other organizations.

Programmers use a RESTful API description language in addition to an application language such as Java, JavaScript, Ruby, Python, or C. The most common API description languages are RAML, Swagger, and API Blueprint.

API languages make it easier to produce Documentation, generate client SDKs, enable discovery, and maintain version consistency and security. Once RESTful APIs are described with an API language, they are much easier to manage and work on collaboratively. These benefits are often realized through tools that can interpret the API language.

Often, developers who want to organize their API specifications don’t know where to start. Should you learn more about RAML, Swagger, API Blueprint, or another API language? Unfortunately, the wide range of languages and tools can be confusing, slowing down API language adoption despite the benefits.

The API languages RAML, Swagger, and API Blueprint are all in wide use. They can all be used to describe endpoints, resources, HTTP methods, representations, and to enable the generation of client SDKs, server skeletons, test suites, and mock servers.

Before deciding which API language to use, the developer should first get an overview of the tools. As an API language is primarily a specification, the value of using the API language comes from the tools surrounding it.

Need for Specialized Tools

Specialized API crafting tools are now available to edit code, provide visual design, and generate the contract, client SDKs, and skeletons. API development tools are starting to resemble traditional IDEs like Eclipse and are often web-based.

As head of the open source Restlet Framework project, I talk to many API developers. Over the years, I listened to many stories on how people approach development. I heard that developers needed a tool that provided more collaboration. API developers told me that they needed something closer to Google Docs. When writing API implementations, they also needed support for business logic and the ability to import other APIs.

Restlet Studio

To meet this need, I drove the development of the free-to-use IDE, Restlet Studio, designed specifically for API developers.

Restlet Studio is a browser-based IDE that is available as a Chrome application and is also compatible with most modern browsers. It is designed to accelerate the design of APIs.

Restlet Studio supports the visual design of APIs, provides Source Code views, handles APIs with a large number of resources or sections, provides skeleton and SDK generation, adheres to REST, and supports multiple API languages including Swagger and RAML initially, with plans to support API Blueprint. For sure, more competition will occur in this space.

Restlet Studio is new and our plans for it are big. We’re really at the beginning of a time of rapid innovation for both API languages and API development tools.

Why is there so much innovation around API languages and API development tools?

In addition to API developers, I also have the opportunity to talk to many people in business who are building API strategies. Businesses are in the middle of an explosion in the number and types of APIs. Today, developers need to create APIs for partner developers, the public, data, business logic, development platforms, infrastructure platforms, User Experience, and user interfaces.

The wide variety of APIs is shown in the diagram below.

Faced with a sharp increase in demand for APIs that serve many different needs, businesses are spending more and more time managing APIs. To make things easier for development, new technology like API languages and tools are appearing rapidly. Demand is driving innovation.

Demand for APIs that businesses need are forcing a change to their approach to software development.

API-Driven Approach

Before we decided to create Restlet Studio, we looked at whether existing software tools like Eclipse could meet the needs of developers. Our decision to build a specialized IDE for APIs was based on changes we saw in software development.

People are starting to develop their APIs first, not the code. Today, in many software projects, APIs are driving the entire development process. In fact, there is a big debate in the software development community about whether an API-first or a code-first software development strategy is better.

A new API-driven approach with a pivot API descriptor, allows for server skeletons and mock generation, up-to-date client SDKs and documentation, and rapid API crafting and implementation. Code-first and API-first approaches can be combined using code introspectors for extraction and code generators to resync.

This change to the development process is creating more demand for people with API development skills. A new generation of tools is being developed to make their jobs easier and more scalable.


Today, there are more types of APIs used by more types of businesses. APIs are used in all layers of a cloud development Stack from the IaaS layer (S3, EC2, Route53), to the PaaS layer (Docker, Heroku, APISpark). We’re at the beginning of this trend and it’s increasing rapidly.

To program this new development stack filled with APIs, a new generation of API languages are emerging. RAML, Swagger, and API Blueprint are three popular API languages. The languages and the tools designed to work with the languages are still in an early stage of development. Although new technologies for API development are becoming more widely used, they are also evolving rapidly.

A new approach to development is replacing the code-first bottom-up approach. This new model is referred to as API-first. I’d love to get your opinion on the different tools and technologies available, including the projects that I’m involved with, Restlet Studio, APISpark, and Restlet Framework.

Additional Information

Typology of Programming Languages Leading to API Languages

Different programming languages serve different purposes. In order to improve the efficiency of software developers, people have moved to higher layers of abstraction.

Here’s a brief typology of programming languages that helps to illustrate why developers are moving to API languages to help them to deal with complex API management problems.

At the lowest level, there is bare metal. This is the hardware layer, machine instructions for x86, CISC, RISC, and other architectures. Machine instructions, while incredibly powerful, aren’t going to be at the top of the list for “hot languages.” The code looks like the stuff you see in the movie, The Matrix.

(100) LOAD:

Use the value on the stack top as a memory address; replace it with the contents of

the referenced location.

(101) POP:

Store the value from the top of the stack in the memory location referenced by the

second word on the stack; pop both.

(110) SUB:

Subtract the top value on the stack from the value below it, pop both and push the


Above the hardware abstraction layer, we have assembly languages. People often use assembly languages such as NASM or TASM for writing drivers. Assembly is very high performance and easier to deal with compared to machine instructions since the commands are closer to human words.

mov eax,1 ; The exit syscall number

mov ebx,0 ; Have an exit code of 0

int 80h ; Interrupt 80h, the thing that pokes the kernel and says, "Yo, do this"

Above assembly language, we have system languages that provide high performance. These are languages like C/C++ or Go. These languages are popular in a list of hot languages.

Going up to higher abstraction levels, we have application languages that improve productivity, are portable, and excel at building business logic into applications. These are languages like Java, PHP, and Visual Basic or Groovy.

Finally, we get to Web API languages. These provide the highest level abstraction and are designed for web scale applications. They are strong in interoperability and Integration. Examples of Web API languages are RAML, Swagger, and API Blueprint.

Be sure to read the next Application Development article: WaveMaker Announces API Gateway for Legacy SOAP-Based to REST-Based App Conversion