21–30 of 59 posts
RAML was the top choice for developer preference and syntax, but industry tooling was much stronger for Swagger.
What we chose was Swagger 2 with the new options for YAML syntax, which gives us good readability/writeability, plus excellent tooling.
I wrote a Python parser for this called RAMLfications ( https://ramlfications.readthedocs.org/en/latest/ ) I actually built the API console for my company - Spotify ( https://developer.spotify.com/web-api/console/ ) - based off of RAML and am in the process of open sourcing the tech behind it. The first bit being RAMLfications, and the second, called Griffin ( https://github.com/spotify/griffin ) is a super alpha ver…
1) Swagger (by far)
2) API Blueprint
3) RAML
Earlier quoted context omitted.
True REST shouldn't require a WSDL-like interface. The semantics of the graph it describes should be enough. This model, however, has yet to be fully realised; largely because of the large upfront cost in R&D. At my work, we are trying to develop in this area, but it's slow going.
Can you expand on that? I've got a mature API that's based around HATEOS, json-schema and HTTP content negotiation. It works really well, but client-side developers always need some time to get used to it, as they expect "REST" to mean "like Rails".
That's great for readability, but it doesn't seem like a perfect choice for a webservice description language, since that content might get hosted and transferred often over the network for clients that might be interested in it.
You could convert to binary to compress it, but that makes it harder for the client, so the friendliest thing would be to convert it to JSON, e.g.: http://my.host/to/a/path/of/my_service.haml.json in addition to the more human-readable haml format at: http://my.host/to/a/path/of/my_service.haml
I wrote a Python parser for this called RAMLfications ( https://ramlfications.readthedocs.org/en/latest/ ) I actually built the API console for my company - Spotify ( https://developer.spotify.com/web-api/console/ ) - based off of RAML and am in the process of open sourcing the tech behind it. The first bit being RAMLfications, and the second, called Griffin ( https://github.com/spotify/griffin ) is a super alpha ver…
What are you using for ref docs? https://developer.spotify.com/web-api/get-album/
how do you create your own "specification" and your own "workgroup"? Can anyone invent some acronym, create their own "workgroup"? Do you need some blessings from YAML or someone else?
Very cool, it feels like WSDL for REST EDIT: spelling
True REST shouldn't require a WSDL-like interface. The semantics of the graph it describes should be enough. This model, however, has yet to be fully realised; largely because of the large upfront cost in R&D. At my work, we are trying to develop in this area, but it's slow going.
This can be both a spec and documentation at once. Client libraries can be generated and services can be stubbed.
Personally, I'd love to see something in reverse: traverse an existing restful service and produce a RAML document.
It's nice, but because of the HAML-like format, there are a lot of empty space characters included. That's great for readability, but it doesn't seem like a perfect choice for a webservice description language, since that content might get hosted and transferred often over the network for clients that might be interested in it. You could convert to binary to compress it, but that makes it harder for the client, so th…