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?

1 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

  • "TALKING to services easier but not much about how the service is written." I do not understand this. I could get the same advantages that I have for the client side on the server (or at least some of them) if I could start with some abstract description of the service. If I had to define some POST functionality, I'd get a method stub with the received values deserialized in values and types that the server side language uses. "The backend is free to serve requests in whatever way it wants." and so is a service description free to include whatever it wants.
    – null
    Sep 4, 2016 at 20:02
  • @null I have edited to give an example, and by "serve requests in whatever way it wants" I mean that the specific logic to process the request is up for grabs. On the client the way to make a call is mostly the same, the consumer usually just provides the parameters like which operation, which resource etc..
    – Siamore
    Sep 4, 2016 at 20:13
  • "just provides the parameters like which operation, which resource etc." - as I said: parsing and deserializing those on the server side is a lot of boilerplate that could all be derived from the description automatically. What if you want to communicate resources both in JSON and XML? More boilerplate to be typed manually (and make mistakes along the way)? No, thanks. I'd rather just add the XML type to the description and be done with it.
    – null
    Sep 4, 2016 at 20:36
  • “parsing and deserializing those on the server side is a lot of boilerplate that could all be derived from the description automatically” “What if you want to communicate resources both in JSON and XML? More boilerplate to be typed manually”, Why do you need a descriptor file for either of these? deserialising params, and XML, JSON conversion is already covered by existing tools.
    – Siamore
    Sep 4, 2016 at 20:42
  • 1
    I agree! and you can! check out raml.org/developers/build-your-api . I have used frameworks for OData that automatically take care of the serialisation, parameter parsing etc.. I am just explaining why anyone would want to have the descriptor file generated. The tools I have used read services, DB tables, views etc to get the information needed to do some neat automations. And I can use that along with the benefits of client side standard interface :)
    – Siamore
    Sep 4, 2016 at 21:12

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.