Api-notebook and WebSequenceDiagrams


#1

Have you used WebSequenceDiagrams to visually document the orchestration inside an API or how multiple APIs from different vendors are stringed together? Do you see value in interweaving RAML with something like websequencediagrams to provide a visual representation either of what happens inside the API or outside in the API Notebook when building an API usage use case?


#2

I hadn’t seen them before. They look like a cool way of indeed documenting both behind-the-scenes of an API as well as visually illustrating usecases, much as the API Notebook scripts through the usecases. They’re ultimately a diagramming tool, so people will need to decide how they prefer to diagram. In any case, having a way to diagram and then share those online would definitely be helpful in the API lifecycle.

Thanks for sharing!


#3

I had seen the tool in earlier versions. It is really cool indeed. Some things I would like to see from WSD, before considering to use it in RAML:

  • A spec of the language (the grammar looks simple enough to backward engineer from their examples, but a more formal definition would be great)
  • Open source implementations of renderers. Right now, it seems that if you want to use it anywhere, you must use their REST Api
  • Also, the API seems to be restricted in use for third party providers: (from their API page) “Please note that subscriptions are for individual users to create diagrams. Requests that appear to be for multiple users may result in cancellation of the account.”

#4

You mean you want a spec for the Web Sequence Diagramming Language? :wink: