machinekit / machinetalk-protobuf

Protobuf declarations for machinekit messages
MIT License
10 stars 11 forks source link

Make API RESTful #44

Open machinekoder opened 8 years ago

machinekoder commented 8 years ago

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:

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 https://github.com/machinekit/machinetalk-protobuf/issues/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 https://github.com/machinekit/machinetalk-protobuf/issues/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:

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 commented 8 years ago

See also apis 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 commented 8 years ago

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 commented 8 years ago

@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 commented 8 years ago

@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 commented 8 years ago

@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 commented 8 years ago

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 commented 8 years ago

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