Search code examples
restweb-servicessoapwsdl

How to describe restful webService

I know two types of webservice.

  • SOAP webservice
  • restful webservice

SOAP webservice can be described in WSDL. So restful webservice how to describe, can let people know how to call.

I'm working with documents. Is there anything else like WSDL.

Solution

  • The Bad News:

    There is no official way to document REST as you are describing. Also keep in mind a WSDL is used to generate code artifacts as well as document the service.

    The good news:

    However you can look at the following four options:

    1. WADL: WSDL equivalent for REST(not widely used or accepted)
    2. RAML: Contender as the standard way to document REST and implement code i.e. WSDL equivalent.
    3. Swagger: Documents the REST service. Not really a WSDL equivalent when it first came out. However this has changed recently. See OpenAPI below.
    4. OpenAPI: Is based on Swagger and it is a way to do top down design.

    The Ugly News:

    Since there is no "official" way some clients will be comfortable with RAML some with Swagger, its is going to be difficult to cater for everyone however this is a minor point.