What to do when API objects and UI names are different?

Question

This question is in reference to API documentation. Say the name of an object is "Action" in the backend, but "Step" in the UI.

We cannot rename objects.

My approach is to explain that Action = Step in the UI, and to use the term "Action" so that people are clear on the objects I am referring to (there are associated objects and filters, etc., such as "approved_actions").

My colleague believes that the better practice is to use terminology from the UI (and of course also to explain that Step = Action).

My thought process is that people making API calls will be more confused if we use UI terminology that doesn't match up to object names. Under each object is a description of what that object is in the UI as well already. I am considering repeatedly defining that in each section for index actions to appease him, but not sure it's really necessary. Any thoughts on this, especially for those experienced with API documentation?

Answer 1

This happens all the time. Sometimes it's not even the programmers' fault. :-)

I agree that you must use the API names. After all, you are documenting what needs to be used in programming. Yes, you can mention the UI label -- which might even change at some point.

UI labels are meant to work for users, and they are constrained by space, localization concerns, style rules, and other considerations. API objects, commands and parameters need only be unique and (somewhat) readable.