How to document a communication protocol on top of message queues and channels

communicationdocumentationmessage-queue

I'm working on a large project at the moment and I'm trying to document the communication protocol that sits on top of a message queue middleware.

The documentation is intended for another organisation that is going to be implementing a new back end to the client.

The messages format uses protocol buffers, so I'm less interested in describing the wire format.

I'm interested in documenting the interactions between the service and client. A typical interaction might be something like:

  1. Client subscribes to Channel1
  2. Client pushes RequestForStream to Queue1
  3. Service reads from Queue1 publishes StreamResponse (containing endpoint to subscribe to, Channel2) to Channel1 and if successful starts publishing notifications to Channel2
  4. Client receives from Channel1 and subscribes to Channel2
  5. More stuff…

How can I best document scenarios like this? Does anyone know of any examples of documented interactions with Queues and channels?

Edit: I am not writing a Message Queue. I am using a JMS-like middleware named Nirvana. I want to document the application built on top of the Message Queue system.

Edit 2: In UML how would I model a Queue or Channel? Would I show them on a sequence diagram?

Best Answer

I am the author of pg_message_queue which is a very light-weight channel/queue system in PostgreSQL designed to facilitate database-level integration. Messages can then be forwarded to a heavier message queue, or the like, or they can just be processed. The use case is for things like "I want to send an email from the database" and helps solve the problem for PostgreSQL without really awkward transactional processing problems that could result.

Our documentation is at http://pgxn.org/dist/pg_message_queue/

I won't say it is the best documentation out there but it is sufficient for our use case. Compare to http://www.rabbitmq.com/documentation.html which is the rabbitmq documentation and you will see how different the requirements of the documentation in fact are.

But like all docs, keep your audience and use case in mind, and go through it conceptually and programmatically.

Edit Ok I see what I misunderstood. I would suggest starting at least with an outline of technical documentation. If you have it from someone else, great. If not, at least come up with an outline of what a technical programmer's manual should cover.

It sounds to me like you are looking at documenting a network protocol rather than an API. Sorry, I did read it and I missed that part. It's still not clear to me if this is direct over TCP, or over HTTP, or something else. To the extent you are reusing other protocols, the work is easier.

Either way, I would divide up the documentation into three sections. The first would cover message structure generally. This would include headers, message body specifications, etc. but would be at a general enough level to provide a reference for section 2.

Section 2 would cover the specifics for each message type. Again it depends on what exactly you are re-using how much depth you need to go into.

Section 3 would provide examples for how the communication would work using sets of mocked up messages.

Related Topic