JSON-RPC Swagger combination

Question

I am considering to implement JSON-RPC for my web service with this library. I would also like to implement Swagger for my service.

However, I am not sure, if these two are a good combination together. In JSON-RPC all methods are behind the same resource, while that does not make any sense in Swagger.

I am wondering the following:

1. Is it possible to combine these technologies in full strength?
2. Is JSON-RPC still a good technology to use? Or is it better to implement it manually?

Your thoughts are appreciated.

Related, unaswered question: Swagger and json-rpc

Answer 1

Coming from the Swagger team, and having little knowledge of JSON-RPC I can provide a partial answer.

Based on what you described in the question, it would definitely not be possible to use Swagger to document such an API. Swagger can only document unique operations where a unique operation is defined as a combination of path and a HTTP verb.

Unfortunately, I cannot comment about the power of JSON-RPC, not because of bias but because I'm not aware enough of its mechanics. To add to that, Swagger does not aim to cover 100% of use cases when describing REST-like APIs, and that does not mean that anything out of its scope is not good.

Answer 2

A word on the API pattern...

JSON-RPC is incredibly powerful. It is transport agnostic, where as REST is locked to HTTP. If you want to use a stream instead of isolated requests, you would have to hack quite a bit. JSON-RPC changes your paradigm from the onset and running your API over any new transport (socket.io, raw binary, ZeroMQ, fax->OCR, sms, anything) is a trivial implementation.

In my opinion, JSON-RPC is to REST, as REST is to SOAP