What's best for a client library: userland code or schema files?

Question

I'm building a client library that consumes a collection of OpenStack API services. I know that as time goes on more services will be added - so I want to come up with a clean and neat way of structuring my client library to minimize development time (for future new services) and avoid duplication.

So far, I've thought of two solutions:

1. Implement userland code from scratch. Each service uses an underlying HTTP client, and for every API operation there is a concrete method in a concrete class that encapsulates logic. This is your standard application where everything exists in concrete code. Advantages are that it is straightforward and obvious for new contributors; disadvantages is that writing code is slow and there is a risk of duplicating boilerplate code.

2. Implement some kind of service description layer - similar to WADLs but lighter and written in JSON. Each description document would act similar to Google's Discovery API where the API's resources are defined using JSON Schemas; HTTP operations are defined with all their parameters, URIs, verb types, expected status codes, etc.; authentication is also defined. Advantages are that it takes less time to write, it avoids duplication, and it forms an explicit contract which is useful for end-user documentation. Disadvantages are that it's quite meta-like and difficult to understand for newcomers.

There are a number of popular client libraries that use this kind of schema pattern, but I'm trying to weigh up its positives and negatives. I'm leaning towards using schemas because I think they'll save time developing and avoid duplication. OpenStack APIs seem to be also moving towards json-schema.

Are there any strong reasons why relying on schemas is a bad idea for a client library, and/or why userland code is a better approach?

Answer 1

Given the way the question is phrased, there obviously cannot be the correct answer, but you are asking for pros and cons. Here I argue solely for concrete code.

My first argument against schema comes along as a question: why not WADL? You want it more lightweight and in JSON! Are you sure you know where to cut the weight on WADL without later learning that you missed some points? Why JSON and not XML? The difference is superficial. My hunch is that you feel that WADL is not the right way to do these things and you think that its problems are weight and XML, but they may be deeper. You give a good arguments yourself: "difficult to understand for newcomers." That means your colleagues cannot help out shortly and you will not understand it anymore after leaving it alone for half a year --- "difficult to maintain" I would call it.

Language design is difficult: You are up to designing a formal language to describe the services you want to attach to. Getting a formal language right is a difficult task, as can be seen in how all programming languages initially have their quirks and evolve over time. There is a good chance that your first design is, well, suboptimal.

Risk of code duplication in my opinion is not an argument against concrete code. Instead of investing up-front in the super-duper all encompassing service description, why not investing just a bit of time constantly in refactoring. Only after having coded some services will you know where the boilerplate code really is that you can factor out into your own support library. As time goes, this support library may do for you what your service description is intended to do --- and better: speed up development of further services.

Spring may be kind of a counter argument. When they started, a lot of coding migrated from Java into XML files and was called configuration. What they actually had was a kind of interpreted, untyped programming language based on XML syntax, including the disadvantage that code brakes in production instead of in the compiler. Then some time ago the new hype was that Spring can now do without XML.

Jetty and Tomcat are similar examples and I guess that Spring was inspired by the XML configuration of Java Servlet applications. But finally Tomcat came out with an "embedded" version where the servlet application can be constructed in pure Java, no external XML configuration required, all concrete code. And Jetty seems to have started with Java-only, concrete code as a design goal.

Bottom line: before moving logic out of your code and into some home-baked description language, think twice, then think it over, then go for concrete code first.-)

It would be interesting to hear after a year how things turned out.