Client Generation


I want to know what people think the best practices are for client generation. For example, in the case of dynamic languages, should there be code generation or a library that reads a RAML file in the constructor?


I too would love to know what people think. For API Notebook we chose dynamic generation without any static code generation, but I know people have started to ask for more of an SDK generator.


I agree, an SDK generator is better when you want to provide an abstracted API on top of your service API, without making the later more complex.

By being able to group and chain service calls, a higher value API can be provided, by keeping the REST API succinct and clean.

It would also be orders of magnitude faster, a largish RAML file can take some time to download and parse, while generated code from that RAML will always parse faster.


I feel like the SDK is better in the long run because as an API vendor, I can just ship prebuilt libraries for every language my clients would want to use and then you could also generate unit tests and mocks for those libraries as well. Beyond that, as a developer, it would give me better insight into what is going on with the code. Should clients follow the API (in terms of methods and functions) that the API notebook uses?


Are there any examples of libaries beyond the API Notebook at this point?


We’ve got it as a near-term goal to break out the client generator currently in the API Notebook into a standalone JavaScript client generator, and as part of that also make more explicit the correspondence between the generated objects and methods and the API’s resources and methods and parameters and bodies. That will give at least an example of what clients could implement.


Do you mean other auto-generated clients for RAML specs? Beyond the API Notebook, the API Console is effectively an auto-generated client, as is the new SoapUI plugin. Also on the roadmap from MuleSoft is one for Java, and of course one for Mule. I know there are specific plans from others in the community for .NET and PHP clients too.


I think that an example client would be awesome because it would let people identify around some sort of standard. Is it on github?


The API notebook and console are both on github, see the projects link above for links to them. The JS client hasn’t been broken out of the notebook yet.


I’m playing with this on: raml2js


I’ve found this:

And it seems this is a WIP project.


entering this discussion a little later… after googling for a while I was quite dismayed, but eventually found this:

I’m going to give it a shot.