Hi, I'm so glad you commented! It took me three days to write this response, mostly due to extreme amounts of waffling. I deleted entire paragraphs, and then put them back, and then deleted them again. /o\

There's a reason to have gettrustgroups as a separate method because it's the only one required for posting, so it's needed even by a minimal client which does only posting/editing.

Ah, when I look at it like that, it makes total sense as to why it got its own method and getcontentfilters didn't make the cut. (It is also now apparent that I am biased toward extracting information from DW when I use the API, and not at all familiar with using it to, say, make posts!)

Indeed, the spec is stealing part of the terminology from LJ and part from DW backend. I'm used to think of the functions in terms of "trust" and "watch", but if the consensus is to replace them with "access" and "subscription", it's fine.

So far, I'm not feeling that either set of terms has the advantage, consensus-wise.

I had thought the list of users in includecontentfilters to be a necessary evil, because they are not limited the same way as trusted users, so it's not possible to get them all in one mask. Don't know if it makes sense to include the list of users in gettrustgroups - the corresponding LJ function does not, it works with masks.

Oh! I hadn't noticed that fundamental difference between trust groups and content filters: you can look up a trust group to find out all the users in it or you can look up a user and get the trust groups it's in, but when it comes to content filters there doesn't seem to be a method for looking up a single user and getting the content filters it's in, you can only look up each content filter and retrieve all the users in it, and then iterate over those lists to find out which filters a single user is in. For some reason, I think I was under the impression that getcircle returned each user's content filters along with their trust mask, but that is definitely not the case, due to the above limitation! (I guess it made just made sense in my head -- when you retrieve information about a user in your circle you want to know if you trust/watch them, if they trust/watch you, what trust groups you've assigned them to, and what content filters you've assigned them to. It's just that we don't actually provide that last bit of info!)

I see what you mean now by necessary evil. :) My quest for symmetry seems hopeless! Oh well.

Or we should not try to keep it compatible with LJ implementation at all, as long as the functions are called differently?

Yeah, it's hard to know what to preserve for the sake of compatibility and what to let go of in the interest of having an API that makes sense for Dreamwidth. If I had designed these methods, I probably would have kept very closely to what was in the existing protocol, but as I am merely documenting, I feel quite free to suggest anything at all!

So what I am thinking now is that the only thing I would absolutely change is the add key of editcircle: rename the key (make it "edit" -- or maybe "set"? "editusers"? "setusers"?), separate the edge key into watch and trust keys, and put the addto/removefrom content filter keys in there:

editcircle

• some key name here that isn't add Array of structs with keys:
  username - the user to edit
  editwatch - 0 to stop watching, 1 to start watching, or not included at all to leave as is
  edittrust - 0 to stop trusting, 1 to start trusting, or not included at all to leave as is
  addtocontentfilters - array of filter ids to add user to
  removefromcontentfilters - array of filter ids to remove user from
  groupmask - the mask to use for this user's trust groups
• setcontentfilters - same as before
• deletecontentfilters - same as before
• settrustgroups - same as before
• deletetrustgroups - same as before

Any thoughts on that? Pros/cons? I always feel like I am not seeing all sides of this code or something.

If I were being ambitious, I would also consider switching all back-end terms to front-end terms instead. But only if other people thought that made more sense, which I am not getting a good sense of right now.

Oh, oh, oh, but I forgot to ask in my post: your patch moves filter setting/deleting out of its own methods and into editcircle, which means that LJ clients who used to use editfriendgroups to change users' masks will have to adapt to a slightly different request structure for the DW API. Specifically, editfriendsgroups accepted a struct of friend ids to its groupmasks key (so the struct was { "friend id 1" => "new groupmask", "friend id 2" => "new groupmask" }). In the editcircle method the structure of the request is different (i.e. an array of user structs: [ {"username" => "name 1", "groupmask" => "new groupmask"}, {"username" => "name 2", "groupmask" => "new groupmask"}]). Do you think that will be a problem, LJ-compatibility-wise?

As I hinted in my post, I kind of find editcircle a bit overloaded. What are your thoughts on moving the filter methods out of editcircle and into their own methods and making them more like the LJ protocol, like so?

edittrustgroups

• groupmasks Struct containing keys:
  userid_x - value of each key is the new groupmask for that user


• set Struct of structs
  groupbit_x - value of each groupbit key is a struct containing keys:
  
  • name
  • public
  • sort


• delete Array of trust group ids to delete.

No, I, um, haven't considered how content filters would work yet vis-a-vis a parallel to that groupmasks key.