NoSQL Message Queue Document Databases – Using NoSQL Document Database as a Message Queue

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.

Communications do not usually only go one way. Parties usually communicate using request-response pairs, which are clearly not one way. I presume that you already know this, so what you are probably thinking when you say "one-way" is not how information flows, but who initiates the requests.

So, yes, the way we usually do things is that only one of the parties initiates requests. Which means that the other party always sends responses.

But there is an exception: the "callback", otherwise known as the "notifier-observer" pattern. It is perfectly fine for one side to send a "register observer" request to which the other side will immediately respond with an "observer registered" response and then, in the future, with one or more "event observation" responses.

Your terminology with "front-end servers" and "back-end servers" and other unrelated entities you call "clients" only confuses things, and you should not have brought it into the discussion. Things are very simple: Within the context of a communication session between two parties, the requesting party is always called a client, and the responding party is always called a server. In your case, your server is what you call a "back-end server", and your client is what you call a "front-end server".

EDIT:

Of course, in order to accomplish two-way communication you need to employ two queues. I have worked on one large-scale system which employed two queues per pair of modules that communicated, (one queue for each "way" in the "two-way",) so trust me, it is not something bizarre.