In the REST world, we have something like a Swagger Specification, which fully describes the contract over a REST interface boundary (between client and server). Those Swagger specifications can be used to auto-generate REST clients, but also to automatically generate documentation for your REST API consumers. These Swagger Specification, moreover, are also a valuable asset w.r.t. CI and versioning of your API.
I was wondering if a similar solution exists in the asynchronous Publish Subscribe world: let's say a typical AMQP Consumer/Producer on RabbitMQ....
Best regards,
Bart
FYI, currently looking into following solutions:
https://avro.apache.org/docs/1.7.7/spec.html
https://github.com/hopped/rabbitmq-avro
Just discovered this, and it is promising:
https://www.asyncapi.com/
Related
OpenAPI is good for RESTful services and at the moment, I'm hacking it to do it for asynchronous messaging system (specifically Kafka) by using POST to a /topic so that I can use redoc do create a website for the API.
I am trying to see if there's already established system of documenting for this. Especially since the GET /events which is used for event sourcing is getting larger and larger by the day.
It seems asyncAPI is basically what you are looking for: openapi but for topics instead of REST endpoints.
https://www.asyncapi.com/docs/getting-started/coming-from-openapi/
CloudEvents is a CNCF backed project for documenting event sourcing, one specification is for Kafka
https://github.com/cloudevents/sdk-java/blob/master/kafka/README.md
If you want a REST API, look at the Kafka REST Proxy
Consider using Protocol Buffers within Kafka.
https://developers.google.com/protocol-buffers/
Protocol Buffers require an API contract (".proto" file) if you want to call or implement a service. The contracts are both human and machine readable.
Protocol Buffers can also be used with other messaging systems and other protocols like HTTP (check out "gRPC" for that). So your documentation / contract is more portable.
Of course this only works for projects having the flexibility to change their payload format.
I'm thinking about trying to implementing a client for a particular json-rpc 2.0 service that could give a user some static typing guarantees. The API in question is very large, so actually writing a full-featured client by hand with all the necessary type information too big of a task for me to be bothered. However I've found via an undocumented http endpoint a large json based schema that seems to describe the entire json-rpc service fully. I'm certain I could write some sort of code generator using this specification. It is too big to paste here.
My question is, is there a standard specification for describing a json-rpc service? I've had a search around and I find a lot of dead links and the official spec[1] for json-rpc makes no mention of a standard schema definition for such a service. The schema I've found seems to be at least partially based off of the json-schema specification[2].
json-rpc
Json Schema
JSON Schema is great for defining payloads formats (you can even use it for REST APIs in OpenAPI) but indeed it won't help describe the "RPC" part, with the methods and entry points.
OpenRPC, created in early 2019, seems to be the most promising
The Ethereum Classic Labs Core (ECLC) team recently created the OpenRPC Specification, aiming to improve all blockchain dapp development. The specification emulates OpenAPI, the successful and widely adopted specification for REST APIs.
The OpenRPC Specification defines a standard, programming language-agnostic interface description for JSON-RPC 2.0 APIs.
Other approaches
Drupal JSON-RPC module provides a discovery endpoint and a Postman collection
The available RPC services along with documentation and usage details can be discovered by sending an HTTP GET request to /jsonrpc/methods.
You can use this Postman Collection with examples and tests.
There might also be interesting things to get from AsyncAPI, gRPC, GraphQL.
Dead
Also citing some other options I stumbled upon but which are dead:
JSON-WSP seems outdated, the Wikipedia page is pending deletion (talk page seems to say this was never actually a standard)
JSON-WSP (JavaScript Object Notation Web-Service Protocol) is a
web-service protocol that uses JSON for service description, requests
and responses. It is inspired from JSON-RPC, but the lack of a service
description specification with documentation in JSON-RPC sparked the
design of JSON-WSP.
JSON Schema Service Descriptor seems to have remained a draft
A JSON Schema service descriptor is simply a JSON Schema with the additional definition for methods.
A bit late but is this what you are looking for?
https://github.com/open-rpc/meta-schema/blob/master/schema.json
For restful services Swagger is a standardized way to describe the interface. Is there already a way to describe Websocket interfaces?
Not at the moment. You may want to join the following discussion about supporting Websocket in the next version of OpenAPI/Swagger spec:
https://github.com/OAI/OpenAPI-Specification/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+Websocket
Possibly ASyncAPI? I haven't tried it myself yet, but:
AsyncAPI provides a specification that allows you to define
Message-Driven APIs in a machine-readable format. It’s
protocol-agnostic, so you can use it for APIs that work over MQTT,
AMQP, WebSockets, STOMP, etc. The spec is very similar to
OpenAPI/Swagger so, if you’re familiar with them, AsyncAPI should be
easy for you.
What about swagger-socket project?
https://github.com/swagger-api/swagger-socket
I like the TDD approach to documenting your restful api with spring-rest-docs. However, I love "API Playground" feature enabled by swagger specification. I wish there was a way to get best of both worlds.
Is there a way to build swagger2 specs from spring rest docs? may be via building custom request/response preprocessors.
Do you have any thoughts or recommendations?
There's not out-of-the-box support for this in Spring REST Docs at the moment. The issue that you opened will track the possibility of adding such functionality. In the meantime, your best bet would be to look at writing a custom Snippet implementation that generates (part of) a Swagger specification.
Typically, a Spring REST Docs snippet deals with documentating a single resource, whereas a Swagger specification describes an entire service. This means that the Swagger specification Snippet implementation will need to accumulate state somehow, before producing a complete specification at the end. There are lots of ways to do that (in memory, multiple files that are combined in a post-processing step, etc.). It's not clear to me that one approach is obviously the right one so some experimentation would be useful. If you do some experimentation, please comment on the issue that you opened with your findings.
There are now REST apis for Mongodb and redis.
I can connect to those databases with my language's driver.
Or I can use the REST api. I understand that the REST api is easier to grok, and easier to convert from language to language. But there's less features.
But is there any reason to use the rest api if I'm already doing fine with the language driver?
Thanks.
In my opinion a RESTful API is useful when you have to integrate multiple different clients in heterogenous environments. It's also good when you need features that are already solved for HTTP – like caches or load-balancing.
REST resources are supposed to capture use-cases of your application. I find it highly unlikely that an API to a database would do that for you. Mostly like the native language driver is the appropriate choice.
Rich web clients can talk directly to it, without any server side mediator. Also, for instance, if you have a JCR repository with NoSQL connector on hostA and NoSQL store on hostB, you're glad for RESTful api.