Should JSON RESTful web services use data contract

Question

This is actually a design question. I\'m wondering if Spring3.0 REST web services that carries JSON payload provide some kind of data contract similar to traditional web ser

Answer 1

The "contract" with "regular" web-services is defined in WSDL files (which include XSDs). With RESTful services these files are called WADL. And spring-mvc does not have support for generating WADLs. (JAX-RS implementations have).

But even if if did, RESTful services are considered more "dynamic" and they don't need to be fixed like that. For example take a look at Facebook's and twitter's REST APIs. They don't provide WADLs or JSON schemas. They provide some free-form documentation of their services. That should be sufficient.

Answer 2

If clients should be enabled to mock the services for unit testing the client (and actually they should), the services should provide a contract. Free form documentation is not a reliable base for testing, because it leaves space for misunderstanding, while contracts don't.

Answer 3

JSON Schema and Hyper-Schema are JSON Schema formats for specifying content and content negotiation.

I have been working on a HATEOAS (Hypermedia as the engine of application state) API, using JSON Hyper Schema. You can go to the URL below, browse around, register, login and do some actions.

Check it out, here: http://direct.psprt.com:8081/

I also open sourced my actual API code thus far: http://bpanahij.github.io/passportedu_schema/

Feel free to take a look, borrow, and comment.

Also, check out the Javascript JSON-Hyper-Schema client. It dynamically builds an HTML client app using Angular, by parsing the Schema provided at a given resources endpoint with the OPTIONS method.

https://github.com/bpanahij/passportedu_schema/tree/master/client