On Mon, Jun 5, 2017 at 5:24 AM, Neale Ranns (nranns) <nra...@cisco.com> wrote:
>
> Dear VPP community,
>
> Some of the feedback we get from users of VPP is that the client-side API is
> not particularly user-friendly – we would like to address this.
I don't know about user friendly; I can wade through the technical details.
I think one thing that is annoying about the API is a lack of consistency.
Here are some examples:
- Sometimes the flag is "u8 is_ipv4", other times it is "u8 is_ipv6".
- Sometimes the flag is "u8 is_ip4", other times it is "u8 is_ip6".
- Sometimes the flag is "u8 is_add", or "u8 is_del", or "u32 is_add".
- "is_enable" vs "is_enabled"
- Some API calls are "foo_add_del", some are "foo_add_replace",
and some are "foo_add" and "foo_del"
I know that sounds trivial. I get that. But it makes for tough anticipation
and violates some principle of least-surprise-or-another.
I get that different people work on different areas, but there needs to
be some consistency both in the names of the API calls and within
the API fields themselves.
It would be documentationally nice for the API comment blocks to
explicitly denote what default values pertain to the fields of an API call.
Similarly, denote what the values of the "invalid" entry are. Is it 0?
Or is it -1 or is it ~0?
> Naturally ☺ In order to create an API that the user community considers
> effective, easy and intuitive to use, it must be a community wide discussion.
> To kick-start that discussion, and to provide some initial focus on the
> specific topics, the document below outlines a set of proposals that we hope
> moves us in this direction.
Is there an explicit list of common complaints that we could work against?
As we all know "It sucks." is pretty generic and hard to fix... :-)
>
> please let us know any opinions you have on this topic, or feedback,
> suggestions, additions, etc to the document, either by replying to this
> thread, unicasting me, or by adding comments directly to the document.
>
> Thanks in advance,
>
> Neale
Thanks,
jdl
_______________________________________________
vpp-dev mailing list
vpp-dev@lists.fd.io
https://lists.fd.io/mailman/listinfo/vpp-dev
