search

jdiegodcp / ramlfications

Python parser for RAML
https://ramlfications.readthedocs.org
Apache License 2.0
234 stars 50 forks source link

Should ResourceNodes include methods? #67

Open pmackay opened 8 years ago

pmackay commented 8 years ago

I've noticed that ResourceNodes include the URI of the resource and the method (GET, POST, etc). Should a ResourceNode just represent the URI and it would have 1 or more associated methods? Most descriptions of resources in REST that I can see suggest a resource is represented by its URI and the methods are operations that can be done to that resource.

I am generating some docs where I want to group methods by resource but this issue created a problem that requires a workaround.

pkucmus commented 8 years ago

:+1: Resource is a thing you want to control with methods like PUT, GET, etc. so for one path there should be one ResourceNode with occasionally more than one method, IMHO.

econchick commented 8 years ago

What about if there are different traits for a method? or security schemes? descriptions? display names? In some form, each method + endpoint will have to be its own object.

pkucmus commented 8 years ago

I didn't knew that methods can be altered that much. But yeah I think it's a good idea to do objects for methods.

econchick commented 8 years ago

Perhaps rather than changing the API, another property could be added to the Root API, something like api.endpoints that returns either a list of strings, or a list of (a new kind of) objects. I'll think on this as I start to implement RAML 1.0 spec, and leave this open for any more comments.

pkucmus commented 8 years ago

Alright, that sounds nice! Thank you!

pmackay commented 8 years ago

Perhaps rather than changing the API, another property could be added to the Root API,

I'd like the behavour of api.resources to change though, so it only returns a list of the resources or URLs, not a list of URL+Method pairs. Thats a significant behaviour change even if the method name doesnt change.

econchick commented 8 years ago

@pmackay that is a significant behavior change, something I'd not be willing to introduce in a 0.x release. How would api.endpoints not address your concern though?

pmackay commented 8 years ago

If api.endpoints was a list of just the URL endpoints it would help, but personally I think its a questionable fix because that's really what api.resources should return IMHO. So is it digging a slightly deeper hole? But it would help :)