Specs, middlewares and consistency
Pierre Chapuis
they lack consistency. Take for instance authentication and api_format.
First, I think that api_format means output format, but there could be
such a thing for input format, in case stuff must be put in the body of
the request and not in the parameters.
Then, to me, authentication and api_format should work almost the same
way. With the current specs:
- authentication is a boolean whereas api_format is a list. Why not
make authentication a multi-valued field like below?
authentication:
- oauth
- digest
- basic
- none
- ...
- authentication can be overridden on a per-method basis but api_format
cannot, why?
On a side note I would also make the 'name' field mandatory.
--
Pierre 'catwell' Chapuis
franck
I am just beginning to get into the specs but as far as I understand they lack consistency. Take for instance authentication and api_format.
First, I think that api_format means output format, but there could be such a thing for input format, in case stuff must be put in the body of the request and not in the parameters.
Then, to me, authentication and api_format should work almost the same way. With the current specs:
- authentication is a boolean whereas api_format is a list. Why not make authentication a multi-valued field like below?
authentication:
- oauth
- digest
- basic
- none
- ...
- authentication can be overridden on a per-method basis but api_format cannot, why?
On a side note I would also make the 'name' field mandatory.
Pierre Chapuis
wrote:
> Currently the spec. is missing the description of the payload. When
> you use a middleware to handle format like JSON, if the method is
> POST
> or PUT, the client should look for a key 'payload', and then
> serialize
> the content to the appropriate format. I'll update the current spec
> ASAP.
Great!
> Hm, the authentication is a boolean that is used to check before
> submiting a request if an authentication has been done. We could add
> another key to specify the appropriate auth. method to use.
OK on that, it can be a separate field.
> - authentication can be overridden on a per-method basis but
> api_format cannot, why?
>
> On a side note I would also make the 'name' field mandatory.
>
> the name field is already mandatory, it's only their as an
> information.
You mean it is optional? That's what is written in the spec. I
suggested to make it mandatory (ie. *not* optional) so that we can use
it to search for APIs on repositories later.
I should have expanded on that more so that you understand the purpose.
SPORE is a ReST replacement of WSDL in the WS-* world. I would also like
to see a replacement of UDDI later on, based on Git-backed JSON
services, with an API described in SPORE (because meta stuff is cool).
In order to make that however, we will need a way to search spec files,
and making the name mandatory would help for that purpose.
I'm OK for leaving it optional though, because I think everybody will
include it anyway, but if someday there are validators for SPORE I would
like to see no name for a spec appear as an error.
> The api_format can be overridden at the method level
> using the 'format' key in the same way as 'api_base_url' can be
> overridden with 'base_url'.
OK, but then why isn't 'authentication' called 'api_authentication' at
the API level?
--
Pierre 'catwell' Chapuis
franck
You mean it is optional? That's what is written in the spec. I suggested to make it mandatory (ie. *not* optional) so that we can use it to search for APIs on repositories later.
I should have expanded on that more so that you understand the purpose. SPORE is a ReST replacement of WSDL in the WS-* world. I would also like to see a replacement of UDDI later on, based on Git-backed JSON services, with an API described in SPORE (because meta stuff is cool). In order to make that however, we will need a way to search spec files, and making the name mandatory would help for that purpose.
I'm OK for leaving it optional though, because I think everybody will include it anyway, but if someday there are validators for SPORE I would like to see no name for a spec appear as an error.
OK, but then why isn't 'authentication' called 'api_authentication' at the API level?
The api_format can be overridden at the method level
using the 'format' key in the same way as 'api_base_url' can be
overridden with 'base_url'.
