Prevent namespace collisions in operation paths about apibuilder

[mbryzek]

swagger-json uses the term 'nickname' as a hint for the name to use for the generated methods. I kind of dislike that approach because it puts extra logic into api.json that really doesn't add any value to documenting the API - i.e. it's just a feature for code generation.

Since the paths are unique - I feel like we can add a small rule to generate better names...

/organizations/:organization/:name/teams ==> getTeamsByName

/organizations/:organization/:name/members ==> getMembersByName

/organizations/:organization/:name/members/:email ==> getMembersByNameAndEmail

so essentially all path parameters joined by "And" come after "By". Non parameter path parts can just be joined

[haywood]

/organizations/:guid ==> getOrganizationsByGuid

I don't think the code can always make the right guess for the name. The code could detect when there is a conflict and only apply the rule to the conflicting methods, but that seems like it is starting to get too clever. Even then, it would not be able to make a good choice in the case of

/poems/:guid

/rhymes/:guid

[mbryzek]

Let's chat - I'm missing some context as the example you gave in my mind
has 0 chance of collision (they are different resources, and thus will have
different namespaces to begin with)

On Tue, Jun 3, 2014 at 4:54 AM, Michael Reed [email protected]
wrote:

/organizations/:guid ==> getOrganizationsByGuid

I don't think the code can always make the right guess for the name. The
code could detect when there is a conflict and only apply the rule to the
conflicting methods, but that seems like it is starting to get too clever.
Even then, it would not be able to make a good choice in the case of

/poems/:guid

/rhymes/:guid

—
Reply to this email directly or view it on GitHub
#9 (comment).

[haywood]

I think you've won me over. We just need a way of excluding the toplevel resource path from the rule so you don't end up with getOrganizationsByGuid instead of getByGuid.

The second example I had is assuming that the toplevel resource had a path of the empty string, and those are paths on operations. But actually those would just be poorly named operations if they were meant to refer to single items.