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.
Related
Currently I am working on a REST API and noticed, that for real REST it is essential to provide the possible HTTP operations of the resource within the HTTP response (e.g. in JSON-LD format).
After playing around with Swagger, I got to JSON-LD and Hydra, which in combination provide the foundation for real REST.
The problem with pure JSON-LD and Hydra is, that there is no real editor (the Playground does help for testing but not for editing).
Then I found Api Platform which sounds quite promising but I could not find any hint, that it supports real REST.
Does API Platform support HATEOAS in terms of providing the possible HTTP operations?
API Platform explicitly supports HATEOAS and they even encourage using Hydra. Their admin UI supports viewing the API through an OpenAPI lens or a Hydra lens.
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/
Spring REST Docs was released recently and the documentation says:
This approach frees you from the limitations imposed by tools like Swagger
So, I wanted to ask when Spring REST Docs is preferable to use comparing to Swagger and which limitations it frees.
I just saw a presentation here that touches on your question among other topics:
https://www.youtube.com/watch?v=k5ncCJBarRI&t=26m58s
Swagger doesn't support hypermedia at all / it's URI centric
Swagger's method of inspecting your code can lag behind your code. It's possible make a change in your code that Swagger fails to understand and won't process properly until Swagger gets updated.
Swagger requires lot of annotation, and it's painful to include the descriptive text you want in an api document in annotations.
There are just some things that Swagger can't figure out from inspecting your code.
In any case, these are just a couple of points. The presenter does a much better job discussing it than I could.
I thought I would chime in to give a little bit more context surrounding Swagger, what it is, and what it is not. I believe this might help answer your question.
Swagger 2.0 is being adopted by a lot of big names and big platforms like Microsoft Azure, Paypal, SwaggerHub.com, DynamicApis.com, etc... Something to keep in mind is that Swagger is very simply a specification. It is not a framework. There are a lot of frameworks out there built to generate Swagger output that crawl through your code looking at your API information in order to build the Swagger 2.0 JSON file that represents your API. The Swagger UI that you see your APIs on is driven directly from this Swagger 2.0 JSON file. fiddler it to check it out
It is important to note that a framework that was created to allow you to "use swagger" is not how Swagger has to work (i.e. it is completely up to the implementation of the 3rd party framework). If the framework you are using to generate your Swagger 2.0 documents and UI is not working for you then you should be able to go find another framework that generates the Swagger artifacts and swap the technologies out.
Hope this helps.
From Spring REST docs:
The aim of Spring REST Docs is to help you to produce documentation for your RESTful services that is accurate and readable
This test-driven approach helps to guarantee the accuracy of your service’s documentation. If a snippet is incorrect the test that produces it will fail.
Spring REST docs advantages:
Documentation is written in the test code so it does not overload main code with lots of annotations and descriptions
Generated docs and examples are accurate because related test must pass
Docs can provide more specific and descriptive snippets
Format is suitable for publishing
Spring REST docs disadvantages:
Requires more work
Documentation provides request/response examples but don't provide interactive tools to modify and try out requests
Swagger advantages:
Quick, automated generation from a code
Interactive request execution - can be used for acceptance testing
Built around the OpenAPI Specification
Swagger disadvantages:
For more descriptive documentation it will require a lot of annotations
Tests are not related to the documentation so sometimes documention may deviate from reality
There is some limitation with swagger and the specific spring stack.
For example : with "param" in your Request Mapping you can define more than one method with the same url ans so simplify your code.
But swagger show you just one method
One disadvantage with Swagger is: it cannot handle models which have cyclical dependencies. If a model has cyclical dependency and if swagger is enabled, then spring boot server crashes.
I'm, going to write a web app, which should be CRUD accessible from both, the web and native mobile device apps. For the latter i'm definitely committed to a REST API. Is it possible to realize that with Meteor.com ? Would it be an option to use Meteor for just the web and a second REST interface to directly talk to the mongo? Since the meteor client listens for changes in the mongodb this should not cause conflicts, does it?
As of 2015, look at Gadi's answer for the Meteorpedia entry on REST APIs, and at krose's answer comparing REST API packages. Discussion for folding REST APIs into core is on Hackpad. This question is a duplicate of How to expose a RESTful service with Meteor, which has much better answers. -- Dan Dascalescu
Old answer (2012) below.
For adding RESTful methods on top of your data, look into the Collection API written for Meteor:
https://github.com/crazytoad/meteor-collectionapi
As for authentication for accessing the database, take a look at this project:
https://github.com/meteor/meteor/wiki/Getting-started-with-Auth
Both are definitely infantile in development, but you can create a RESTful API and integrate it with a mobile native client pretty easily.
There are a lot of duplicates of this question. I did a full write-on on this in Meteorpedia which I believe covers all issues:
http://www.meteorpedia.com/read/REST_API
The post reviews all 6 options for creating REST interfaces, from highest level (e.g. smart packages that handle everything for you) to lowest level (e.g. writing your own connectHandler).
Additionally the post covers when using a REST interface is the right or wrong thing to do in Meteor, references Meteor REST testing tools, and explains common pitfalls like CORS security issues.
If you are planning to develop a production application, then Meteor is not an option right now. Its under constant change, and there are still many common features it has to support before its ready to use, which will be quite some time.
For your Question, Somebody has already asked and answered the question about support for file uploading in meteor(also contains HTTP handing related information).
How would one handle a file upload with Meteor?
I'm an experienced client application developer (C++/C#), but need to come up to speed quickly on writing server side code to perform RESTful interactions. Specifically, I need to learn how to exchange data with OpenSocial containers via the RESTful API.
The RESTWiki is a very good resource and then there is the classic "How I explained REST to my Wife".
However, don't forget to go read about it directly from the source, it is not as difficult a read as it may first seem.
And I am assuming you will be doing REST over HTTP so this will come in very handy.
Lastly, considering OpenSocial supports the Atom Publishing Protocol, this will be useful.
Enjoy.
RESTful Web Services
I found this this to be a good introduction to RESTful web apps, although it doesn't refer to OpenSocial containers.