Names vs object

[ndw]

With respect to names vs. objects, do you think the API should try to hide that distinction or make it explicit? Personally, I'm inclined to make it explicit.

In the users model, for example, I created methods role_names, add_role_name, etc. This is distinct from the database model which has security_database which returns the name of the database, not the database object itself.

[paul-hoehne]

Under the principle of least surprise, anything we do should be consistent. So roles should return a collection of objects and role_names should return just the names. That's in line with the other comment about only loading the objects when users read a value other than something like the name. However, from the perspective of someone who's never used MarkLogic before, would this confuse them? Would they know that they're supposed to work with roles or role_names? (Assuming you had both a role_names and roles method on an object.)

One way is to allow them to get just the name or the object, but require them to add the fully formed object. But I guess some things just require the name of the object and not all the details for that object. Hmm... A the very least the security_database method should be renamed to security_database_name and another methods should be added that returns the security database.

[ndw]

Yeah, it's tricky. I hate forcing the distinction on users but I can't see how to avoid it and maintain reasonable performance.

[paul-hoehne]

Let's say we let them get back the collection of lazy loading objects. Most of the APIs in the management APIs return the name of the related objects. Do you think this would work? For example:

my_roles = my_user.roles()
for r in my_roles:
    print(r.name())

That would be cheap because the iteration is over the role names returned with the user object's response. That would cover simple enumeration of names. But:

my_role = my_role.roles()
for r in my_roles:
    for p in r.privileges():
        print(p.name())

This would be less performing because it would require the roles to be fetched from the server in order to deference their privileges. I'll defer to you on that since your use case is a great one to test the validity of this api style approach versus the big config file approach.