2

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?

jdessey
  • 690
  • 6
  • 14
  • REST should not need any documentation - per definition, the resulting data should be sufficient enough for clients to navigate further or process data, otherwise you have no pure "REST" but rather a RPC using HTTP. On the other hand, it depends on your case, for example there is a JSON schema in the making. – Smutje Aug 20 '14 at 19:03
  • Presumably a client who is querying a bookstore and listing the books would likely want to deal with the return value as a collection of book objects. Is that a fair assumption? If so, lacking any of the listed options, they would need to implement their own Book class...as would every other client. So the resulting data on its own is "sufficient for clients to navigate further or process data". I just aim to make the processing more convenient. – jdessey Aug 20 '14 at 19:16
  • Here's a [self documentation example](http://restcookbook.com/Basics/hateoas/). Clients only need an underlying HTTP library to start using the REST service. Take a look at what the returned structures are and marshal them into objects using a marshaller of your choice (say gson from google for json). – Deepak Bala Aug 20 '14 at 19:18
  • HATEOAS looks to be about discovery of subsequent operations and linked resources. I think that's a different topic (could be wrong). Let me try to ask more simply...If I want to create a new object via a REST interface, this object will have attributes. Without the options I listed, how do I know the names and data types of these attributes? – jdessey Aug 20 '14 at 19:50
  • Just found this question http://stackoverflow.com/questions/22427747/what-is-wsdl-equivalent-in-restful-ws-if-nothing-how-consumer-generates-requir?rq=1 . The answer implies that a xhtml response provides a form with attributes and data types. This is close to what I'm looking for (still can't easily generate classes from it). But is this methodology part of any documented standard? – jdessey Aug 20 '14 at 20:19

1 Answers1

1

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.

adrobisch
  • 316
  • 1
  • 3
  • Swagger with the codegen module seems like it may work, providing data types to the client with the ability to generate client code. I'd be happier if there were a more widespread methodology (as there is with wsimport for SOAP) but many people seem to be hung up on saying that there's no reason to represent your entities on the client side. – jdessey Aug 21 '14 at 20:02