Create a web service description and derive code from it or the other way round?

Question

I have written some small HTTP services myself and the clients that consumed them. There's a question on CodeReview in the hot questions about a wrapper for some RESTful API which made me wonder, should one ever write such wrappers "by hand"?

My workflow was usually:

1. Write server side code
2. Test it or, to be honest, try it
3. Write wrappers on the client side to use the service

I heard about languages that describe services (WSDL) and that they allow the automated generation of such wrappers. That makes sense: if the service changes, so do the wrappers.

I never used such service descriptions for the services I wrote. However, I noticed the duplicated effort of writing code both on server and client to a common "interface". There's also a lot of boilerplate code involved, like making requests, serializing/deserializing data into JSON, XML or whatever format is used. It would be nice to derive the wrapper code automatically.

It is mentioned that the description languages are meant to be written automatically themselves, derived from some service code already written.

Why is that? Why would I not start the process by writing a description of the service, so that I could then create wrappers for it on both the server and the client side automatically? Or at least create the classes/method stubs with already (de-)/serialized parameters, etc. Why is it necessary to write code, to derive a description from it to derive code from that. Or is my understanding of service descriptions just wrong? I'd like to improve my code by using service descriptions.

When I start a next project that does not have to apply to any existing code, isn't it the best idea to create the description first, to have some abstract definition of the whole thing and derive everything else from it?

Answer 1

Service descriptors are basically a "standard" metadata format for services.

This allows us to create client libraries that know how to do the boilerplate tasks like endpoints for each resource, CSRF handling etc..

This lets the client use a service over a "standard" interface (Like SQL, check out OData docs to see what I mean), in contrast to ad-hoc web services which can have whatever interface the developer wants.

So WSDL, OData etc specify a lot of stuff that makes TALKING to services easier but not much about how the service is written.

The backend is free to serve requests in whatever way it wants.

Given this freedom for the backend the things that can be automated are... limited. Standard things like generation of the classes for each resource and specifying serializers etc already exist.

And generation of descriptors is usually automated so I see limited use of going descriptor file first. In fact doing so might just unnecessarily constrain the backend code.

EDIT: Adding an example to illustrate,

Say the abstract description of the service says that Groceries is a resource, on the client we can say AND implement:

• get the top x number of entries for groceries
• sort the groceries
• get grocery and related groceries

I'm just giving a few examples but there are a ton of other stuff you can do, check http://www.odata.org/documentation/odata-version-2-0/overview/

EDIT2: I explained the scenario where we want to use infra instead of having it generated for us.

There are some newer approaches that actually do take the descriptor file and do interesting stuff with it (code generation, automated tests etc).

I have seen related work around RAML (http://raml.org/developers/build-your-api) This is newer stuff but maybe a better way. It does seem to be a simpler one at least :).

EDIT3: Somewhat related, check out GraphQL from Facebook too, Its tied to React I think but the idea can be generalised, Meteor's apollo is also doing some interesting work around this.

P.S OData is a REST based specification for web services read more at odata.org