High Level Groups API Approach Ideas

groups_api_high_level.md

What we have now

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.

What we need

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.

Proposed /groups endpoint

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.

GET /groups behavior

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

Next Steps (Help me!)

• 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.

Does the overall approach sound OK?

Yes! 🎉

As you’ve noted elsewhere, this doesn’t currently account for different authorities. That may end up being fine, though: we might not need to support this new functionality for other authorities.

Can you help me give the target_context parameter a better name?

The badge endpoint (to list the number of annotations on a given page) uses a uri parameter. That seems like a reasonable option, unless there’s some important context I’m missing (which there may well be).

I like the approach of creating a new endpoint for this; that makes a lot of sense to me, especially given Nick’s suggestions on where we take the API. Depending on how it all pans out, it might well make sense to remove groups information from the profile endpoint entirely. As I understand the history, it’s there more as a matter of convenience than a matter of design.