Description and discovery of RESTful web services

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, 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 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.