As you may know, WSDL is used for describing the functionality offered by a SOAP web service. For a SOAP web service, this is a widely accepted standard and is supported by many enterprises today. In contrast, there is no such standard for RESTful web services, and you may find different metadata formats used by various enterprises.
However, in general, you may see the following goals in common among all these metadata formats for RESTful APIs, although they differ in their syntax and semantics:
- Entry points for the service
- Resource paths for accessing each resource
- Allowed HTTP methods to access these resources, such as GET, POST, PUT, and DELETE
- Additional parameters that need to be supplied with these methods, such as pagination parameters, while reading large collections
- Format types used for representing the request and response body contents such as JSON, XML, and TEXT
- Status codes and error messages returned by the APIs
- Human readable documentation for REST APIs, which includes documentation of the request methods, input and output parameters, response codes (success or error), API security, and business logic
Some of the popular metadata formats used for describing REST APIs are Web Application Description Language (WADL), Swagger, RESTful API Modeling Language (RAML), API Blueprint, and WSDL 2.0.
We will have a more detailed discussion on each of these items in Chapter 7, Description and Discovery of the RESTful Web Services.