API ConsumerAPI ManagementApis in the Enterprise: Field MusingsCitizen DeveloperEnterprise Application IntegrationSOA

Why API Code Generation is like Printing Colour in Black and White

Andy Medlicott - Chief Architect - digitalML
Andy Medlicott – Chief Architect – digitalML

We want to get results quicker don’t we? Building services and APIs is no different. How do we get services tested, deployed and being useful sooner? That’s easy isn’t it? I’ll use a code generator to speed things up. All I need to do is make a WSDL, WADL or Swagger file from my specifications and use one to generate source code and… Voila! One service client or server stub in a few seconds. Neat eh?

That’s the theory.

I won’t go into the first challenge of getting a contract definition file from a specification… needless to say that converting Excel spreadsheets is not my favourite activity… as my main problem is the output…

Contract definition formats, such as WSDL, WADL and Swagger are exactly that – they only define the contract. They don’t attempt to describe anything behind the contract. Nor should they as that’s not what they are intended to do.

But that’s like saving a colour image as black and white when you need it to be printed in colour! You can see the subject – but all the colour is missing!

Going beyond the contract

Pretty much every specification document  I’ve seen contains FAR more information than can be expressed in one of these formats… design decisions, non-functional requirements, orchestration details, data mapping, use cases and activity diagrams… the list goes on and on.

As none of this information makes it into the contact definition format – none of it makes it into your code gen!

And you either have to generate once and then maintain it separately, or you have to try a tricky synchronisation process to keep source code and specifications in sync… neither are good options in my opinion!

So I have been using code generation direct from the specification.

By using a Service Design Platform, such as ignite, you can generate your service code directly from your Service Specifications. A Service Design Platform provides  a single source of information for every artefact used in the service design process, including detailed service models, business capabilities, metadata and mappings to your provider and consumer systems. As well as eliminating  spreadsheet working, these systems provide nicely defined specifications that are far richer than any service contract and crucially ensure that all this information is incorporated into your service code.

Your service “stubs” are no longer stubs. They have the control logic captured in the use cases and process orchestration parts of the specification… They have test cases for the edge conditions described in the specification… This means less work for developers… which means less bugs, quicker testing and more importantly – services deployed quicker!



Related Articles

Check Also