eclipse-ditto
Add custom HTTP REST API facades wrapping Ditto message commands
Use-Case
A micro-service providing certain additional functionality to a thing, e.g. managing historical time series data, is registered to ditto via e.g. websockets and processes certain messages send to digital twins. A client application may now send messages to a thing to get it's history. For this to work it has to know what messages exist, what parameters they expect and what the response looks like. Typical API knowledge.
Currently this knowledge has to be managed outside the ecosystem with a third-party application / channel.
Basic Idea
A micro-service may use a descriptive interface to ditto to share it's capabilities in a way that ditto may serve dynamic REST endpoints according to the specification of the service.
Further Thoughts
It would be handy to have also a dynamic swagger doc reflecting addtional functionality.
Ditto should cache this registered API and also provide means to integrate this into health check requests.
Discussion
Let's discuss!
Thanks for the initiative @w4tsn! So you suggest to have another service beneath e.g. search that is "history" and that exposes its own Ditto API? I highly +1 that! For the format it would be interesting to discuss typical use cases (I can share some of ours here, and you may also have some), or what do you suggest for next steps?
@JulianFeinauer
For the format it would be interesting to discuss typical use cases (I can share some of ours here, and you may also have some)
Great idea! I will prepare something next week.
Let me add some more thoughts / bit of rephrasing what I have in mind. Basically this is about the possibility to provide our own "custom" services in a transparent way which would also allow us to provide them in other languages and runtimes.
In our specific use-case we added a micro-service providing our custom history API. We want to have this API simply be available through ditto messages and secured by the policy framework of ditto. Our frontend developers however want to have a typical REST API with Swagger docs. Of course they can use the generic REST API for ditto messages, but this is not really an expressive way of exposing our API.
Right now we communicate the API capabilities in a separate document in our own "swagger-ish" language which is a bit of a pain in the *** for both sides - especially because API spec is an already solved problem so to speak. The micro-service expects certain ditto message topics, fields in the messages payload etc.
This is only one service with one additional functionality. We might come up with additional services in the future which face similar problems. In order to solve this it would be nice to define the API in a descriptive way (maybe through Vorto Models / Generators, Operations and Events come to mind) and provide this to ditto so it may update it's available REST API for twins and features dynamically according to the new services API spec.
EDIT on 2021.08.12:
The API facade needs to allow all kinds of REST API methods. Currently with ditto messages API every request is a POST. One problem with this are semantics of the resulting API a thing (or a delegate service) exposes. E.g. if I just want to GET data, I don't want to send a POST. The other problem is actually a technical one: in our tests we discovered a bug in Firefox that would prevent using a POST that is answered with a 303 See Other. While this use-case is covered in RFC 2616 it seems to be so uncommon that even well-known browsers don't implement that right.