While working on a small REST system I noticed how boring (and incredable time consuming) all that work is. Typing in the classes, implementing the REST-API calls and then document the whole stuff for all the other developers.
After using the modeling tool now the changes of the model are pretty instant and more or less interactive – but now the documentation is still very time consuming.
Sebastian Heidbrink pointed me to an external tool set named swagger, which could help me saving time.
Swagger works the way, that you annotate your source code with information and then from this information the system generates a JSON based schema model, which defines the parameters location, parameter types and response type for each REST call (and some more stuff).
Several REST-calls may be bundled into defined REST-APIs.
The JSON resources can be static files located on any server. Now with a tool named SwaggerUI one can visualize the API and test it. The last part is really fun debugging !
I actually changed the kind of working with swagger for me. I added several Smalltalk classes in Gemstone to be able to define the JSON based schema model and now added Smalltalk code on the REST class class-side with information, what calls are belonging to the API, what parameters are needed etc.
Then I added a small REST runtime system and for each request now the system is looking for the JSON schema nformation about the executed call, look for the parameter descriptions, retrieves the parameter values, checks them and if all is ok, call the domain specific method.
ZincHTTP now not only serves the API, but also the specification of the API.
After having done this – one thinks about how the Modelling tool can create support for the Swagger Schema – but I will talk about this in a later posting