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, for RESTful web services, there is no such standard 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
HTTP methods allowed to access these resources, such as
GET
,POST
,PUT
, andDELETE
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 the 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, The Description and Discovery of RESTful Web Services.