What are API specifications?

Although SOAP APIs are often cumbersome and difficult to understand, they do have some benefits. One of the benefits of SOAP APIs is that the structure must be specified following strict programmatic rules. When a SOAP API creates a WSDL file to describe the API capabilities, the fact that it is required to follow this strict set of rules means that it is written in a way that computers can easily understand. This makes it easy to create a lot of general-purpose automation for these kinds of APIs. If a computer can understand the layout of an API, you can automatically generate some kinds of documentation, tests, and even code from that specification.

However, RESTful APIs are a bit different. They follow an architectural style that was laid out by Roy Fielding in his doctoral dissertation. This means that there are general principles that they follow, but there is not a strict protocol that they must adhere to. This balance between structure and flexibility...