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 services which follows contract-first design. I know that JSON has schema similar to XSD but where does it fits in spring ? Background: I consider using json as the payload of a client server architecture project where the client is .NET based application and data contract should provide a way to handle multiple versions of the client. The client should be able to post data structures to the server. Or maybe I should take a schema-less approach and use "Simple Data Binding" which is similar to XmlAnyElement?

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