Make API RESTful

[machinekoder]

The current Machinetalk API is probably not what one would call RESTful. A RESTful API consist of a small set of commands, resources, a defined serialization format and simple interfaces. Machinetalk is very close:

• Protobuf works very well for consistent data serialization
• We have something like resources -> I would call it services
• We have relatively simple interfaces thanks to ZMQ

The only problem I see so far - we mapped the CNC stack API to the messaging layer. Basically mixing up protocol level types and RPC types. To create a RESTful API we should cleanly split up those two types of message identifiers to minimize the number of commands. See #40 and http://hintjens.com/blog:86

For example the types for the HAL remote component are in https://github.com/machinekit/machinetalk-protobuf/blob/master/src/machinetalk/protobuf/types.proto#L266 whereas the probably should be in sub-message of the protocol level Container message. The Container message should only contain types relevant on protocol level, meaning MT_PING, MT_ERROR, ...
The type for HALrcomp should be in a sub-message e.g. halrcomp defined by a protobuf extension (see #42), same for all other services.

The idea is that nobody needs to touch the protocol if not necessary. Extending machinetalk can then be done in a fork as well. Development of new services does not need to happen on the protocol level. The protocol level can be generic.

E.g. we have two basic types of "channels" at the moment:

• PUB-SUB : to publish updates, need MT_PING, MT_FULL_UPDATE and MT_INCREMENTAL_UPDATE
• REQ-REP or RPC: need MT_PING, MT_PING_ACKNOWLEDGE, MT_REQ, MT_ACK, MT_NACK and so on

Basically these base channels should have as few messages types as possible all implementation level protocol, such as halrcomp should be based on it. This will significantly decrease the effort to maintain the different protocols and to document the RESTful API. Encryptions and reliabilty can be added on base protocol level.

[machinekoder]

See also
source https://www2.deloitte.com/content/dam/Deloitte/sv/Documents/technology/Tech-Trends-2015.pdf

The Machinekit CNC stack is clearly somewhere in the 80s, with Machinetalk we should bring it into this century.

[bobvanderlinden]

This sounds like a good idea. Am I right in thinking this is a container protocol where all existing protocols can be based upon (not just halrcomp)?

[machinekoder]

@bobvanderlinden Yes, I am also trying to automate the process of creating the bindings with code generation. Can you point me an example for the implementation of your node.js bindings?

[bobvanderlinden]

@Strahlex This is how the files for Javascript are generated: https://github.com/bobvanderlinden/machinetalk-protobuf-node/blob/master/scripts/install.js#L26
It uses protobuf.js.

[machinekoder]

@bobvanderlinden And here it is used: https://github.com/bobvanderlinden/node-machinetalk/blob/master/statusclient.js Would you be willing to write a code generator once I have a proper model for the reusable Machinetalk sockets? The bindings can be implemented pretty similar in every language. Having a code generator will save use a lot of maintainance work.

[bobvanderlinden]

Ah, like that. Generating the application-facing API itself. In Javascripts case, I'll have to think about whether it's better to generate the code or whether it's doable at runtime (the protobuf-'bindings' are already generated, javascript can read all of its properties and create its functions). Whatever the case, it would indeed be nice to have a language-native layer on top of protobuf that moves along with the developments of machinetalk-protobuf. That way it should also be possible to have a similar interface between python, javascript and possibly C/C++. This goes further than what you've mentioned in this issue, should this be a separate issue?

[machinekoder]

@bobvanderlinden Yes, I think we should move this discussion to a new issue.