Should multiple IDs in a URL all be named {id}?


#1

Suppose we had an API for a repository of data about politics.

Would it be better to document it like this (concise but possibly confusing) …

 /parties/{id}/candidates/{id}  

…or like this (a bit wordy, but clear)?

/parties/{party-id}/candidates/{candidate-id}

Apart from style, would the choice affect whether the API Portal can handle this RAML?


#2

Good question!

When I see the URL all together (or as nested resources) I usually like the {id} and {id} style since it’s concise while the other option sounds redundant.
BUT, if you think the ways the documentation will be displayed (for example, a list of parameters), the name will be repeated granting place to confusion.
Considering that, I might be biased to go for the second option.

That’s being said, let’s go to the second question. The RAML is valid, and API Portal will be able to handle it (remember that the portal is just the repository + documentation + links to other tools). But right now (I just tested the scenario) the current API RAML Console doesn’t behave good with parameters with the same name. Furthermore, it will depend on each different tool and how are these tools implemented, the support to it (once again, from RAML point of view, that’s valid).
Considering that, I might be biased to go for the second option.

Final Score:
Second option 2.
First option 0.

(It’s a shame, my favorite team lost).

I will be raising some issues about the tools I work with, and I would love to read @dmartinez thoughts about this as well.
Cheers!