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:
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.
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?