Date   

Some initial questions...

James Milligan
 
Edited

- Where can API keys be found or generated? Since the API is still in alpha, is it just a case that they are unavailable right now?
 
- Are there plans to support custom fields that can only be edited by mods/owners? I see the moderator notes field, but in the future it would be good to have distinct named fields that can be referenced by calling applications (think external identifiers and so on).
 
In my case, with our membership system, I can invite or add a user to the group with a known email address, but if they change their email address later on in Groups.IO I lose the only 'link' I have on a technical level with our membership system. Storing their membership number against their account (which won't change) will allow me to pivot around those instead of email addresses, and remove them once their membership lapses. Which leads me onto...
 
- Are there plans to allow searching for members (aside from having to fetch all members and search within the results)? If custom fields are supported, I'd like to be able to search based on these as well.
 
On a separate but related note, one approach that could work well for getting members without searching or knowing their internal ID is through allowing reference by a hashed version of the user's email address (including aliased addresses). If a member exists that has that email address on their profile their object is returned. Mailchimp does something similar which work well enough.
 
Thanks in advance!
 
Kind regards,

James Milligan
Need to integrate with the Groups.io API in Java? Check out the Groups.io API Java client


Java API client/wrapper

James Milligan
 
Edited

As I'll be needing to develop code to interact with the Groups.IO API, I've decided to try and make this available open source from the off. The GitHub project is available here: https://github.com/lake54/groupsio-api-java and a CLI example here: https://github.com/lake54/groupsio-api-java-example
 
They're both stubs for the moment, I'll push up what I have soon once API keys are available and I can definitively query a group and get a good response, but any and all contributions will be welcome. I'll try and get it published on Maven Central in the future once there is a stable enough build.

Kind regards,

James Milligan
Need to integrate with the Groups.io API in Java? Check out the Groups.io API Java client
 


Re: Some initial questions...

 

Hi James,

On Tue, Aug 8, 2017 at 11:00 AM, James Milligan <james@...> wrote:
- Where can API keys be found or generated? Since the API is still in alpha, is it just a case that they are unavailable right now?

I will get you a demo API key off-line. 

 
- Are there plans to support custom fields that can only be edited by mods/owners? I see the moderator notes field, but in the future it would be good to have distinct named fields that can be referenced by calling applications (think external identifiers and so on).

I'd like to have something like that, but it will have to wait, and it may be a part of a future feature where owners can set up questionnaires for their users. In the mean time, moderator_notes is probably your best bet.
 
In my case, with our membership system, I can invite or add a user to the group with a known email address, but if they change their email address later on in Groups.IO I lose the only 'link' I have on a technical level with our membership system. Storing their membership number against their account (which won't change) will allow me to pivot around those instead of email addresses, and remove them once their membership lapses. Which leads me onto...

- Are there plans to allow searching for members (aside from having to fetch all members and search within the results)? If custom fields are supported, I'd like to be able to search based on these as well.

I will add a search method. Object IDs do not change, so that'd be a good way to reference members.

Also, I've just pushed a bunch of updates to the API docs, including a section talking about versioning. Please let me know if you have questions.

Thanks,
Mark


Updates

 

Hi All,

I've made some changes to the API with respect to how updates/deletes are going to be made. The docs previously said that you would post a JSON object to update something. I have changed that so that instead you POST specific fields to update. I think this will reduce the chance of errors. It's also how the Stripe API works.

Also, now the /updateuser endpoint is working, for a subset of possible values.

Thanks, Mark


Re: Some initial questions...

James Milligan
 

On Thu, Aug 10, 2017 at 12:18 pm, Mark Fletcher wrote:
I will get you a demo API key off-line.
Received, thanks.
I'd like to have something like that, but it will have to wait, and it may be a part of a future feature where owners can set up questionnaires for their users. In the mean time, moderator_notes is probably your best bet.
OK. Our mods wouldn't be used to using that section for notes on members so it should be easy to store some structured data in there for now without much risk.
I will add a search method.
Great :)
Object IDs do not change, so that'd be a good way to reference members.
OK, although just thinking about this a bit more for my particular case I'm not going to have the object ID at the right point depending on how the member is being invited/added. I'm unfamiliar with the direct add functionality at the moment - is it the case that when a user is 'direct add'ed to a group via the web UI, a stub user account is created? If so, with the API, as long as I can get that object ID (or even the full user object) in the response to a 'direct add' API call that could work at least for direct add scenarios (I assume for more traditional invite scenarios the user isn't created until they accept the invite?)

Also, I've just pushed a bunch of updates to the API docs, including a section talking about versioning. Please let me know if you have questions
Looks good especially the versioning bit, however I feel it's inaccurate to state that "changing the length or format of object IDs or other opaque strings; this includes adding or removing fixed prefixes" are backwards-compatible. They might be from an API perspective, but if external systems are going to be storing these IDs they mustn't change - ideally at all, but if they must then it should be against a specific API version.

It would be nice if more of the error responses used their related HTTP codes - 401/unauthenticated (the 'real' meaning), 403/unauthorized, 429/rate limit and so on rather than bundling them into a custom error object - avoids deserialising them when a simple HTTP code check would suffice.


Re: Updates

James Milligan
 

To me, the 'standard' (for some definition of standard online these days!) is for POSTs on creation, PUTs for providing whole objects for update (or creation), and PATCHes for providing partial objects for update.

In practice, I don't think it really matters as long as the request types and expected behaviour are documented appropriately.


Updates

 

fyi, I've completed the /updategroup endpoint, and it should now be working completely. I've also fixed a bunch of errors in the docs around /updategroup.

Mark


Re: Java API client/wrapper

James Milligan
 

The client repo has now had an initial set of code published to it, implementing login functionality, fetching current user information, their subscriptions, and members in specified groups (requires mod/owner perms).

The example repo has also been updated.
--
Kind regards,

James Milligan
Need to integrate with the Groups.io API in Java? Check out the Groups.io API Java client


Feedback 2017-08-12

James Milligan
 

Just a few things I've picked up this evening:

API errors
https://groups.io/static/api#get-topics consistently getting BAD_REQUEST with this one despite a valid group_id set (https://api.groups.io/v1/gettopics?group_id=1405) that the calling user has access to (as an owner). Originally thought it might be because of 0 topics/messages, but even after adding a couple of messages to the group I'm still getting the same response (repro'd with Postman to skip the Java client).

Docs
(Generally) example schemas don't always tally with response attribute listings, mostly just a case of some missing fields. I'm using the schemas to generate POJOs which means I'm sometimes missing a couple of attributes.
(Generally) some required tags missing orange label formatting
(Suggestion) displaying requirements for calls in a consistent way - permissions, plan levels, and required params.
https://groups.io/static/api#get-member is missing mandatory group_id param in example request
https://groups.io/static/api#the-user-object missing comma after time_pref value (invalid JSON)
https://groups.io/static/api#get-topics typo in is_closed attribute name (response attributes)

--
Kind regards,

James Milligan
Need to integrate with the Groups.io API in Java? Check out the Groups.io API Java client


Re: Feedback 2017-08-12

 

Hi James,

On Sat, Aug 12, 2017 at 2:41 PM, James Milligan <james@...> wrote:
Just a few things I've picked up this evening:

API errors
https://groups.io/static/api#get-topics consistently getting BAD_REQUEST with this one despite a valid group_id set (https://api.groups.io/v1/gettopics?group_id=1405) that the calling user has access to (as an owner). Originally thought it might be because of 0 topics/messages, but even after adding a couple of messages to the group I'm still getting the same response (repro'd with Postman to skip the Java client).

Sorry about that. That endpoint should be considered not implemented right now (and the docs are wrong). I've just added the 'NI' in the docs for that.

 
Docs
(Generally) example schemas don't always tally with response attribute listings, mostly just a case of some missing fields. I'm using the schemas to generate POJOs which means I'm sometimes missing a couple of attributes.

Good catch. I will update the examples on Monday.


(Generally) some required tags missing orange label formatting

I see that in the get topics endpoint, which I'll fix next week. Please let me know if you see them anywhere else.

 
(Suggestion) displaying requirements for calls in a consistent way - permissions, plan levels, and required params.
https://groups.io/static/api#get-member is missing mandatory group_id param in example request
https://groups.io/static/api#the-user-object missing comma after time_pref value (invalid JSON)

These are fixed.

Thanks,
Mark 


Re: Feedback 2017-08-12

James Milligan
 

On Sat, Aug 12, 2017 at 04:18 pm, Mark Fletcher wrote:
Hi James,

On Sat, Aug 12, 2017 at 2:41 PM, James Milligan <james@...> wrote:
Just a few things I've picked up this evening:

API errors
https://groups.io/static/api#get-topics consistently getting BAD_REQUEST with this one despite a valid group_id set (https://api.groups.io/v1/gettopics?group_id=1405) that the calling user has access to (as an owner). Originally thought it might be because of 0 topics/messages, but even after adding a couple of messages to the group I'm still getting the same response (repro'd with Postman to skip the Java client).
Sorry about that. That endpoint should be considered not implemented right now (and the docs are wrong). I've just added the 'NI' in the docs for that.
 
Ah, that'll explain it :) I'll stick an exception in that for now and just comment out the code temporarily.
 
 
Docs
(Generally) example schemas don't always tally with response attribute listings, mostly just a case of some missing fields. I'm using the schemas to generate POJOs which means I'm sometimes missing a couple of attributes.
 
Good catch. I will update the examples on Monday.
 
 
(Generally) some required tags missing orange label formatting
 
I see that in the get topics endpoint, which I'll fix next week. Please let me know if you see them anywhere else.
Great, thanks on both. I think that's the only one actually.
 
 
 
(Suggestion) displaying requirements for calls in a consistent way - permissions, plan levels, and required params.
https://groups.io/static/api#get-member is missing mandatory group_id param in example request
https://groups.io/static/api#the-user-object missing comma after time_pref value (invalid JSON)
These are fixed.
Thanks - although the get member group ID in the request (2) differs to that of the response (5).

Cheers for the speedy updates!
 
--
Kind regards,

James Milligan
Need to integrate with the Groups.io API in Java? Check out the Groups.io API Java client


Updates

 

Hi All,

I just pushed a bunch of updates to the api server and docs. All of the member-related endpoints except invite now work. I've also combined some different permissions to make checking easier and more clear. I've also updated many parts of the docs and have refreshed all the example schemas.

Please let me know if you see or experience any errors.

Thanks,
Mark


API updates

 

Hi All,

I've added the /invite, /searchmembers and /getsubgroups endpoints today. In addition, I added the missing 'parent_group_id' field to group responses.

Thanks,
Mark


Re: Updates

James Milligan
 

Hi Mark,

The /updateuser endpoint seems to accept (200 OK) my requests, but doesn't actually proceed to update the user:

curl -X POST \
  https://api.groups.io/v1/updateuser \
  -H 'authorization: Basic ...' \
  -H 'cache-control: no-cache' \
  -d time_pref=time_absolute
It just returns the existing user as it was beforehand. I did try with a password=1 request to see whether it would return password_too_short but no luck :(

It would be really nice (rather, simpler for me!) if the API accepted JSON on the way in as well as for the response.

--
Kind regards,

James Milligan
Need to integrate with the Groups.io API in Java? Check out the Groups.io API Java client


Re: Updates

 

Hi James,

On Thu, Aug 17, 2017 at 11:15 AM, James Milligan <james@...> wrote:
Hi Mark,

The /updateuser endpoint seems to accept (200 OK) my requests, but doesn't actually proceed to update the user:

Please try it now. I've also updated it to take some additional parameters.

Error objects now have an "object" field, to be consistent with the other objects. I also changed user_status_notconfirmed to user_status_not_confirmed, to be more consistent.

 
It would be really nice (rather, simpler for me!) if the API accepted JSON on the way in as well as for the response.

Understood. For at least the time being, I need to keep the calls as they are. I'm doing the API this way because I can repurpose the existing web code, with not a lot of change, to also run the api server, and I can have both servers share the same code. A lot less development risk, and I'm able to get more done quickly. Plus it's how Stripe's API works, and I try to copy them whenever I can because I think their API is very well thought out. :)

I hope tomorrow to have a system in place where you can easily diff different versions of the API docs, so you can see what's changed.


Thanks,
Mark


Re: Updates

James Milligan
 

On Thu, Aug 17, 2017 at 04:08 pm, Mark Fletcher wrote:
Please try it now. I've also updated it to take some additional parameters.
Hmm, still getting 200 OK but the object hasn't changed :-/
 
It would be really nice (rather, simpler for me!) if the API accepted JSON on the way in as well as for the response.
Understood. For at least the time being, I need to keep the calls as they are. I'm doing the API this way because I can repurpose the existing web code, with not a lot of change, to also run the api server, and I can have both servers share the same code. A lot less development risk, and I'm able to get more done quickly. Plus it's how Stripe's API works, and I try to copy them whenever I can because I think their API is very well thought out. :)
No worries - #wishlist for the future then!
I hope tomorrow to have a system in place where you can easily diff different versions of the API docs, so you can see what's changed.
Smashing - that'll really help.
 
--
Kind regards,

James Milligan
Need to integrate with the Groups.io API in Java? Check out the Groups.io API Java client


Re: Updates

 

On Fri, Aug 18, 2017 at 9:33 AM, James Milligan <james@...> wrote:
On Thu, Aug 17, 2017 at 04:08 pm, Mark Fletcher wrote:
Please try it now. I've also updated it to take some additional parameters.
Hmm, still getting 200 OK but the object hasn't changed :-/

Ok, I think it's fixed now for sure.

Thanks,
Mark 


Friday updates

 

Hi All,

There is now a working changelog/diff function for the API docs. It's at 


It's not perfect, but should hopefully be helpful.

I've also changed the URL for the API docs; it's now at https://groups.io/api

The /createsubgroup endpoint is now working and the docs have been updated with the correct parameters.

I noticed today that I'm a bit inconsistent in using "bad_request" versus "invalid_value" in errors. My gut says to get rid of one of them. I will figure that out early next week.

Please let me know if you see anything or have suggestions. 

Thanks,
Mark


Re: Updates

James Milligan
 

Yep, working for me too. Cheers!
--
Kind regards,

James Milligan
Need to integrate with the Groups.io API in Java? Check out the Groups.io API Java client


Re: Friday updates

James Milligan
 

Thanks Mark. I guess it depends - bad request feels more like there's a field or otherwise structural issue with the request, whereas invalid value is (to me) saying that the request itself is valid, but what you're trying to set is wrong. If you had to choose one I'd stick with bad request though.
--
Kind regards,

James Milligan
Need to integrate with the Groups.io API in Java? Check out the Groups.io API Java client