Search code examples
javarestwsdl

REST client API data types

My basic assumption is that with a SOAP web service, the provided WSDL would contain XSD describing the data types sent and received. When developing a client in Java, tools like wsimport can be used to generate classes corresponding to the elements of the WSDL, and in particular the complex data types. This frees the developer of the SOAP client from creating classes representing the return types (and/or complex parameters).

By contrast, with REST api's I have not typically seen -

  1. A WSDL 2.0 http://www.ibm.com/developerworks/webservices/library/ws-restwsdl/
  2. A WADL http://www.w3.org/Submission/wadl/
  3. (If server and client both Java) just provide the same JAXB classes used on the server side
  4. XSD

So my question is - as an author of a REST server side api, what is the best way to provide the relevant data types to clients?

Solution

  • Since the user of a REST API will most certainly be a developer there is no one answer to this. As a developer I would consider a client library (developed by the creator of the API) in my favorite programming language the best option.

    You already mentioned WADL for documentation, but there is also:

    • Swagger: probably the most mature and feature-rich REST API documentation approach. It includes a embeddable API browser.
    • RAML: a YAML based specifcation standard for REST APIs. Multiple projects were created around this, e.g. a (experimental) JAX-RS generator, including annotated Jackson classes or a raml2html converter.

    There is support for XSD of Json Schema in both alternatives. By using one of them, you should be able to create a documentation which is helpful for all possible API users.