Background/History

APIs have been around since the earliest days of software development. There has always been a need to document these APIs to facilitate teams collaboratively creating complex software. Originally, this documentation took the form of just regular formatted documents designed for human consumption.

As the use of the Internet grew in the 90’s, companies realized that they needed a way to describe their APIs that could be read and processed by other computers and development tools. The advent of web services drove this shift in mindset from documentation being solely for human developers to being something that could also be used by other computers to improve productivity and data integrity.

WSDL and XML Web Services

Web Services Description Language (WSDL) was one of the first widely used documentation formats to describe web services. Traditional web services are an evolution of the older Remote Procedure Call (RPC) technology that allowed different components of a software system to communicate over a network. Web services took the base concepts of RPC and allowed them to efficiently operate across the Internet.

A defining characteristic of these web services was the use of XML to structure the information being passed in both the request and the response. WSDL followed this module and used XML to document the operations available in the web service and the structure of the XML that was being passed in the request/response. For example, a web service may have an operation named “createBook” that takes an XML data structure such as “<book><title>20,000 Leagues Under the Sea</title><author>Jules Verne</author></book>”.

A partial WSDL for the above structure might look like the following:

<message name=”Book”> <part name=”title” type=”xsd:string” /> <part name=”author type=”xsd:string” /> </message> <portType name=”Books”> <operation name=”createBook”> <input name=”newBook” message=”Book” /> </operation> </portType>

This structure allows an application to know that the available operation or action is “createBook” and that the operation takes two parameters “title” and “author” both of which are string values. The application can then validate the request before processing it to ensure that it is in the correct format. Additionally, through the use of the XSL, this WSDL documentation can be converted into a human-readable web page. So a single document can serve both the application and the developer.

WSDL and SOAP Web Services

A need arose for a more consistently formatted structure for web services after awhile. With regular XML web services, it is up to the creator of the service to define the format and structure of the WSDL. However, that complicates integrating services from multiple different systems or vendors. Additionally, it doesn’t provide any standard mechanism for defining security requirements for the web service. Simple Object Assessment and Plan (SOAP) was developed as a standard way to structure web services to promote interoperability and security. SOAP is an extension of standard XML web services with strict rules around the formatting and structure of the XML request and response. The WSDL documentation format for SOAP web services was also extended to facilitate documenting these web services in a standard way.

OpenAPI (Swagger) and REST Web Services

The API approach we now refer to as REST (Representation State transfer) APIs first originated in a doctoral dissertation by Roy Fielding in 2000. Roy wanted to design an approach to API services that could easily be leveraged by any system without the complexities of SOAP web services. His solution was to develop an architecture that revolved around resource or data object types and then implement a stateless communication protocol based on HTTP verbs and the json data structure.

So now, developers and systems know about an objects data structure, such as a book, and then use standard HTTP verbs to control the interaction with that data structure. This simplifies the development and consumption of these services since support for these types of interactions are built into most application frameworks. Using the create book example above, with a RESTful web service, the developer would make a simple “POST https://api.example.com/book” http request passing a simple JSON body such as the following:

{ title: ‘20,000 Leagues Under the Sea’ author: ‘Jules Verne’ }

This format is simpler, uses less bandwidth, and can be efficiently processed by most programming languages and frameworks without needing memory-intensive XML parsing systems and complex schema validators.

A new format for documenting these RESTful web services was also needed. That format is known as the OpenAPI Specification format (originally known as Swagger). This specification format follows the same base principals as RESTful web services and uses either JSON or YAML data structure to document the available objects, operations, requests, and responses. The following is an example of the OpenAPI specification in YAML format.

openapi: '3.0.0' info: version: 1.0.0 title: Book Management paths: '/book': post: summary: "Create a book" description: "Creates a new book." operationId: "createBook" responses: '200': description: "successful operation" requestBody: content: application/json: schema: type: object properties: title: description: Name of the book. type: string author: description: Name of the author. type: string

YAML provides an easier to read structure for the API documentation and there are several Javascript libraries that convert this documentation into user-friendly HTML pages. The above example just says that there is a URL at “/book” that the user would make an HTTP POST request to passing a json object with fields for title and author. The OpenAPI spec goes beyond just defining the call structure though to supporting information about error states, example code, and additional narrative documentation for the developer.

Unifying your documentation

Neither WSDL or OpenAPI are better than the other. Both WSDL and OpenAPI documentation formats have their use cases and will likely exist within an organization depending on your API landscape. What is important is that your APIs are documented and that your development teams can easily locate and access the documentation for your APIs in whatever format they may exist in. Apiboost provides a unified catalog of your API documentation in a consistent and usable format to facilitate your team in quickly locating and utilizing your APIs.