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
Related
Currently, I'm working on a project where I using websockets, in my past projects where I've been using mostly RESTful standard that was simple to document using Postman or Swagger, but actually I've spotted issue because Postman and Swagger seem to don't support WebSockets.
My question is how you're documenting WebSockets? Any information will be helpful but I'm mostly seeking some tool that will allow me to store documentation and share it with others.
The only thing that I've found is https://hoppscotch.io/
UPDATE 2022: Postman introduced new tools for documenting APIs including websockets and grpc what exactly resolves this issue and provides great tools to document further APIs.
tl;dr use AsyncAPI for it.
Here are some learning materials:
WebSocket, Shrek, and AsyncAPI - An Opinionated Intro
Creating AsyncAPI for WebSocket API - Step by Step
From API-First to Code Generation - A WebSocket Use Case
Official example of AsyncAPI document for real WebSocket API: Gemini API. For preview in AsyncAPI Playground click here.
YouTube presentation from EDASummit called An Opinionated Intro to AsyncAPI with WebSocket and Shrek and live stream that covers the first two articles mentioned above.
I've been googling some time for a searching solution for documenting WebSockets, and my answer is some kind of disappointing - Postman, OpenAPI or RAML don't support WebSocket documentation. So the only rational way to document parts of software that are using WebSockets is to write technical documentation by hand.
Checked examples on bigger organizations like Slack and so on, and they use the same practices for documenting real-time sockets, just write technical documentation by hand, I don't know how good that solution is but basically it will work so it's fine.
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.
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/
Let's say I have some service that talks over ZeroMQ sockets, and I want to provide access to that service to a single-page web application. I'd like the web app to talk to a service that provides a REST API (for control and queries) and WebSockets (for monitoring), and which does this by talking ZeroMQ to the first service. I'd like to write this in Scala.
What options are available to me for building that second service?
A very integrated solution would be to use Akka/Play2 for this.
Akka would be the core component talking to the ZeroMQ socktes via akkas ZeroMQ Module, which gives you a nice Scala-API and Akka/Actor integration. This Akka/Actor system can than be accessed via HTTP/WebSockets by using either play-mini or play2 which mainly differ in the style of defining HTTP endpoints.
For REST API I would recommend Spray - a nice library with a very concise and flexible DSL for defining web services. We've integrated Spray into our current project and are pretty happy with it. As for play-mini, AFAIK, it depends on the entire play2 project, so you'll end up with a lot of stuff you don't need.
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.