There are currently two definitions of the v2 api: 1) The v2.rb routes file, and 2) the apipie documentation. There is currently no restriction that the routes used by calling the api directly actually be implemented or work in apipie. This seems like an enormous gap with the potential for errors in both hammer (which uses #2) and the UI/community (which uses #1).
What if the v2.rb routes were auto-generated by apipie? In this way only documented routes would be accessible to consumers (along with all the supported parameters).
Speaking of parameters, there are instances in controllers where processed parameters behave in conflict with documented apipie parameters.
PUT /something/:id/relation/:foo_id <-- defined in v2.rb
PUT /something/:id/relation {foo_ids: [foo_id]} <-- defined in apipie and in v2.rb
The actual controller, though, has a single method for processing this call and if not written correctly will not work for one or the other. If apipie were the "golden" definition of the api, then the first route would not be callable from the UI/community since it was not defined in apipie. If it was defined in apipie, then presumably it would be in the tested suite and the conflict in the controller would have been caught by QE/devs.
Will Martin's dynamic apipie bindings provide a solution for this perhaps? We need some way to force our documented api to be the only api consumable by callers. (Are we going to make bindings in all languages, including javascript, output from apipie and require using that.)
I know there is a lot going on in the code base, but I'd hate to see things like this be added to "tech debt."
Thoughts?
···
--
@thomasmckay
–
“The leader must aim high, see big, judge widely, thus setting himself apart form the ordinary people who debate in narrow confines.” ~ Charles De Gaulle
“Leadership is about making others better as a result of your presence and making sure that impact lasts in your absence.” ~ Harvard Business School
It allows to get the route information from routes into the apipie documentation.
>
> There are currently two definitions of the v2 api: 1) The v2.rb routes file,
> and 2) the apipie documentation. There is currently no restriction that the
> routes used by calling the api directly actually be implemented or work in
> apipie. This seems like an enormous gap with the potential for errors in
> both hammer (which uses #2) and the UI/community (which uses #1).
I'm not sure I understand the issue properly. Could you elaborate more,
ideally with some specific example?
– Ivan
>
> What if the v2.rb routes were auto-generated by apipie? In this way only
> documented routes would be accessible to consumers (along with all the
> supported parameters).
>
> Speaking of parameters, there are instances in controllers where processed
> parameters behave in conflict with documented apipie parameters.
>
> PUT /something/:id/relation/:foo_id <-- defined in v2.rb
> PUT /something/:id/relation {foo_ids: [foo_id]} <-- defined in apipie
> and in v2.rb
>
> The actual controller, though, has a single method for processing this call
> and if not written correctly will not work for one or the other. If apipie
> were the "golden" definition of the api, then the first route would not be
> callable from the UI/community since it was not defined in apipie. If it was
> defined in apipie, then presumably it would be in the tested suite and the
> conflict in the controller would have been caught by QE/devs.
What about loading all the routes into documentation (provided the PR mentioned
above works for us) and eliminating the number of routes defined to the smallest
set that works for us?
I'm a bit worried about using apipie as source for routes definition, as it
goes against the Rails conventions (I usually don't like this kind of argument,
but might be confusing at the end, therefore I would like to solve the issue
from opposite direction)
– Ivan
···
----- Original Message -----
Will Martin’s dynamic apipie bindings provide a solution for this perhaps? We
need some way to force our documented api to be the only api consumable by
callers. (Are we going to make bindings in all languages, including
javascript, output from apipie and require using that.)
I know there is a lot going on in the code base, but I’d hate to see things
like this be added to “tech debt.”
Thoughts?
– @thomasmckay
–
“The leader must aim high, see big, judge widely, thus setting himself apart
form the ordinary people who debate in narrow confines.” ~ Charles De Gaulle
“Leadership is about making others better as a result of your presence and
making sure that impact lasts in your absence.” ~ Harvard Business School
