GET /profile
Returns a profile
object that contains, among other things, a groups
property, an Array of objects; that part of the schema looks like:
"groups": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"public": {
"type": "boolean"
}
}
}
},
Where id
is the public ID of the group and public
is a Boolean meant to imply that the group is world-readable.
We need a service that can return a list of groups that take into account the current target context (i.e. the document that the client is targeting—“where the client is”, URL-wise).
In addition, the returned object representing each group should more clearly communicate what “type” of group the group is. While introducing a type
property with enum values private
, open
(and later restricted
, etc.) may be a little too facile/naive, it may well serve the purpose for the moment. I will give this more thought—but basically I’m trying to satisfy a need coming from Sheetal/the client for being able to tell what type of group a group is.
The public
property is a little wiggly. I need to do more research to see how the client is using it and whether it should remain at all or morph into the new attribute we’re talking about here.
The API bears the responsibility of sorting returned groups.
I propose creating a new resource API for groups
, starting with a GET
service.
GET /groups
optionally accepts a request parameter; I’m going to call this target_context
for now, though I really need input on what to call it. It represents the URL of the target document where the client is currently “being displayed”. This will help the service determine which groups to return.
I like developing this as a brand-new endpoint so I can poke specifically at the groups pieces of it without jumping into mangling GET /profile
.
And there’s no reason that the service/controller behind this endpoint couldn’t be reused to generate the groups attached to GET /profile
profile objects.
End result: standalone groups
resource API and you can still use GET /profile
to get the right groups (GET /profile
will need to be updated to accept the optional target_context
param in this approach).
Future additions here might well include a POST
service for creating groups.
There are four “modes” that this API can take based on the combination of the presence of the target_context
parameter and whether there is a logged-in user or not.
- non-auth’d user, no context: returns non-scoped (i.e. global), world-read groups. At present, this is only the global Public group.
- non-auth’d user, with context: returns world-read, non-scoped groups (again, “Public”) as well as any world-read (“open”) groups whose scope is satisfied by the target document’s URL
- auth’d user, no context: returns global-Public group as well as any groups this user has membership in (currently: private groups)
- auth’d user, with context: Returns global-Public, groups that this user has membership in (private groups) as well as any world-read (“open”) groups whose scope is satisfied by the target document’s URL
- Does the overall approach sound OK?
- Can you help me give the
target_context
parameter a better name?
If so, I’ll cough up a proposed schema.
Re group types: should the client tell what "type" of group a group is? Should the client even have a concept of group type? I wonder if the way it could work is that it's up to h to send the client "links" such as the URL for a group's activity page, the URL for leaving a group, etc in the JSON repr of a group that h sends. Rather than the client generating these links itself based on the group's pubid. Then, since an open group will not have a URL for leaving the group (the leave URL is simply missing from the JSON repr that h sends), then the client doesn't render a leave button. And the same for whether the client should show the activity page link: if there's no activity page URL in the JSON that the h API sends for a group, then the client doesn't show an activity page link for that group. So there would be no group "types" ("open", "private", etc) as such in the client, and no "if it's an open group then X"-type logic in the client. Just "if group has activity URL then render activity link"-type logic in the client.
But: no doubt the client is currently riddled with logic about what type of group a group is (public, private or publisher).