search

NREL / api-umbrella

Open source API management platform
http://apiumbrella.io
MIT License
2.01k stars 324 forks source link

RAML Support? #47

Open brylie opened 9 years ago

brylie commented 9 years ago

What are your thoughts on API Umbrella as it relates to the RAML specification?

brylie commented 9 years ago

This could, for example, lead to capabilities such as API auto-configuration.

darylrobbins commented 9 years ago

RAML is also fantastic for offering auto generated API documentation. This is how we are planning to document our API.

perfaram commented 9 years ago

IMHO, RAML support would be a great feature. It would be really useful, i.e when you use RAML to design your own APIs and want to quickly get up and running with api-umbrella :+1:

brylie commented 9 years ago

I set up a Bountysource page to support this issue financially.

kyyberi commented 9 years ago

I would reformat the needs here. RAML style API description is one approach. There are atleast two more significant API description frameworks/specifications: Swagger 2.0 (YAML based as is RAML) and API Blueprint.

Umbrella should offer means to input specification file in above given formats and set routing and all in Umbrella according to specification. Parsers for RAML, API blueprint and Swagger exists.

At least API Blueprint has Ruby on Rails binding https://github.com/apiaryio/redsnow as well as RAML https://github.com/coub/raml_ruby

darylrobbins commented 9 years ago

I think this issue is currently too nebulous. We should try and be more concrete about what we would expect to happen when we import an API specification file. What would the MVP look like vs. what other features our on the wishlist? I think what an imported API spec means is going to depend a lot on how one is mapping urls to backend api's. Care to offer some concrete examples of what kind of configuration you'd like to be done automatically?

@kyyberi Excellent point, but I think we may want to focus on one spec to start and go from there. Also, unfortunately, the RAML Ruby library is incomplete and not overly useful at the moment.

We have been doing some work on generating HTML documentation from a RAML spec.

darylrobbins commented 9 years ago

The ideal scenario would be to only have to support one spec format, which the others could be converted into.

kyyberi commented 9 years ago

I agree that one format only support is ideal. Who's going to make the selection which it is? :) I guess RAML is strong candidate. At the moment I don't have a concrete example to offer and currently my time is limited. Therefore I can't promise that I will ever offer it. Anyway starting with minimum read in approach would make sense...and minimize the amount of waste.

If and when RAML ruby parser is not very useful and if the development seems to lag, perhaps it makes sense to start with some other format. Neverthless, this API-first design driven support will be awesome feature when it's done :)

darylrobbins commented 9 years ago

I think whoever ends up implementing the feature gets to decide. :) I agree that RAML is a strong candidate. I see more about it than the other two projects. But yes, it looks like the RAML Ruby parser was left in an incomplete state and hasn't got much love since (it's not an official project). We gave up on the gem pretty early and decided to use JavaScript for most of our RAML needs thereafter.