How can I use apiary with JSON-RPC

Question

I am trying to use apiary.io to document a JSON-RPC based API. I can get the pages formatted, but console simply does not work.

With JSON-RPC you typically only have 1 URI, such is the case with our API. Because of this, when attempting to define the methods, the blueprint editor gives the warning

Action with method POST already defined...

I figured I could ignore this, but in the apiary console when testing it will only returns the example response for the first action defined. Does anyone have a work around for this?

Answer 1

From what I understand from JSON-RPC spec and examples, multiple requests and responses could work for you better than defining POST endpoints multiple times.

# My API

## JSON-RPC [/endpoint]

### Doing something [POST]
+ Request Sum of numbers (application/json-rpc)

        {"method": "sum", "params": {"a":3, "b":4}, "id":0}

+ Response 200 (application/json-rpc)

        {"result": 7, "error": null, "id": 0}

+ Request Posting a message (application/json-rpc)

        {"method": "postMessage", "params": ["Hello all!"], "id": 99}

+ Response 200 (application/json-rpc)

        {"result": 1, "error": null, "id": 99}

Cons: Your API will be squashed into one or two endpoints and individual requests won't be visible in ToC.

Pros: The request-response pairing logic in Apiary mock server will then allow you to use some strategies (also described on the page linked above) to invoke different response than just the first one. However, as these strategies work only (in the time of posting this answer) with headers or status codes and they do not inspect body of incoming request's payload, you probably still won't be able to easily distinguish between your requests in console.

Possible workaround would be to give extra headers to your requests, such as X-Request: 1, X-Request: 2, etc., so the mock server can distinguish between them and return you the right response.

Answer 2

You can use trick with anchor, unique fragment path in api endpoint url.

# Group Awesnome JSON-RPC API

## Entity A [/#A]
### Procedure A [POST]
### Procedure B [POST]

## Entity B [/#B]
### Procedure C [POST]
### Procedure D [POST]