Proposal for /v2/Guild APIs

[SamHurne]

In hopes of creating a good discussion on how the guild-related API could be expanded, I've created a proposal for some additional endpoints. This proposal is to take the current /v1/guild_details API and expand it into additional endpoints.

• New /v2/guild endpoint, based on /v1/guild_details but with additional information. This new endpoint would add home world ID, member count, influence, and merits count. See guild.js for an example.
  • I was unsure about including the guild's Message of the Day, as often times guilds use the motd for private data, like Teamspeak server & password information. I've left this out, but it would be nice to find a place to fit it into an authenticated endpoint if anyone has any ideas.
• New /v2/guild_roster endpoint, including an array of guild members for a particular guild. See guild_roster.js for an example.
  • Authenticated endpoint - if the authenticated user belongs to the guild_roster requested, the request is serviced. Only members of a guild should be able to see who else is in that guild.
• New /v2/guild_ranks/ endpoint, detailing all of the ranks and rank details of a guild. See guild_ranks.js for an example.
  • Authenticated endpoint - The data is probably not as sensitive as that found in the /v2/guild_roster endpoint, but because it expands on a field within that endpoint, I've made it match for now. I could go either way on this though.
  • This is also probably less important since it's really only useful to expand on the rank field of members listed in the /v2/guild_roster endpoint.

I'm also thinking about guild upgrades and build queue, but I haven't been able to come up with a reasonable schema for those yet. Perhaps it could look similar to the proposed /v2/skills API: one endpoint to retrieve details about each guild upgrade/consumable with another endpoint to detail what a guild actual has and what is in the queue.

[tynril]

Besides that, I have mixed feelings about this one. While I agree that accessing guilds would be awesome, there's the constraint of confidentiality. The MOTD seems clearly out of bounds, but what about the influence and merits? The upgrades? Even the guild bank?

Maybe the public version of the API should limit itself to very broad information like in the v1, while an authenticated version could be more thorough in its data, including basically everything that is available in the game (which is what you've listed, what I mentioned earlier, plus some more, such as events, guild missions status, ...).

[lye]

While I agree that accessing guilds would be awesome, there's the constraint of confidentiality.

The rule of thumb we use is basically to mimic the in-game visibility. I think I'd put all of these behind authenticated endpoints, even the influence/merits. I think there's a case that could be made either way for the member count and upgrade/buff status, but it's probably better to err on the side of safety.

Also, I find /v2/guild/:id/ranks to look prettier than /v2/guild_ranks?guild_id=:id, but that's bikeshedding.

[tivac]

• Definitely prefer /v2/guild/:id/ranks and /v2/guild/:id/roster over separate endpoints. It's cleaner, and fits in better with how I'd like us to structure API URLs going forward.
• For guild rosters last_online seems like it should be a full timestamp time instead of a delta.
• For guild ranks does it make sense for permissions to be an array of strings containing the permissions the user does have? Seeing all of them in object form is nice, but I'm not sure how useful that data is. Thoughts?
• MOTD behind authentication seems like a definite yes
• Would love to see guild events/research behind authentication as well

[SamHurne]

• Using a timestamp for last_online does probably make more sense. What would be the preferred method of represending the date/time in the JSON? Something like 2012-04-23T18:25:43.511Z (ISO 8601), or Unix timestamps?
• I see no problem with /v2/guild:id/ranks and /v2/guild/:id/roster instead of separate endpoints. Sounds good to me.
• I'll try to put together/add something for upgrades/events
• permissions - An array of strings does seem like an improvement. I feel like there might be an even better way of representing the permissions, but I haven't thought of one yet.
• Would it be reasonable to have the /v2/guild endpoint such that if requested without authentication, the basic, public information is returned, but with authentication, expanded information is available?

Also, full disclosure: I am not a web developer, therefore if there are any best practices that I'm breaking, do tell 😃

[lye]

What would be the preferred method of represending the date/time in the JSON?

Definitely ISO 8601.

Would it be reasonable to have the /v2/guild endpoint such that if requested without authentication, the basic, public information is returned, but with authentication, expanded information is available?

Seems fine to me. There might be some issue with communicating an error for improperly-sent credentials, but that might be better fixed with good documentation.

[SamHurne]

I've updated the PR according to the latest comments and have added examples of a new guild_upgrades endpoint. Some notes:

• Renamed guild_id and guild_name to id and name.
• The example now includes an authenticated /v2/guild and an unauthenticated /v2/guild. The unauthenticated version matches the current /v1/guild_details endpoint.
• The authenticated /v2/guild endpoint now includes guild upgrades, including build queue, unlocks, consumables, and boosts. Each of these has an ID, and their details are retrieved via the /v2/guild_upgrades endpoint.
• Updated all date/times and durations to follow the ISO 8601 format.
• I've left the ranks as I had them, as it occurred to me that if we just list the permissions that a rank has, it's not as clear of what permissions are available and what permissions the rank does not have. Still thinking about this one...

Also working on examples for guild missions. I suspect it will look similar to what I have for the upgrades, with active_missions and available_missions objects as part of the response for the authenticated /v2/guild request.

[lye]

I think we might also be able to include each member's current character name in the guild roster if they're currently logged in.

[kjintar]

Will there be any restriction about whose authentication is needed to request the entire information pool?

It seems very inappropriate to some of my guild mates that you only need the authentication of one member to get access to the entire "who is online" list and roster. This also applies to spam concerns. A potential spam bot can request all online players of a guild (my guild has 480 members...) by obtaining the authentication of only one of the guild members.

An ingame permission would be the best but i think this is not possible. But what about setting up the roster to only show up if the authenticated player is guild leader?

[lye]

But what about setting up the roster to only show up if the authenticated player is guild leader?

Not a terrible idea. It might make sense to initially release it restricted, then evaluate whether or not relaxing the restrictions would be beneficial (and/or give us time to add additional features to limit unintended/undesirable data exposure).

[Ruhrpottpatriot]

While I agree to the problem, that opening the roster to everyone, I want to raise a counter argument: What if a guild website has a private area for guild members where they can see who is online. Maybe I want to see if my friends are online from outside of the game. Not every guild has a TS and checking via forum is somewhat clanky.

I think this information is valuable to people besides the guild leader. My initial thought would be to add a permission system ingame, so the guild leader can grant those permissions, since the problem does not only applies to member lists, but also the guild bank, and possible other things.
This would work like this:
Guild leader can set additional permissions in the ranks tab, somewhat along the line of: "Out of game Permissions". There he can check various flags which could include:

• Can see Memberlist
• Can see Guild Bank

If the user has permission he can request the information in all other cases he gets a 401 error. This should work, since we are already checking if the user has the correct API-Key, an additional check shouldn't be the problem.

[kjintar]

The workflow should look like this in my opinion:

You develope a guild website, the guild leader generates an api key and verifies that the guild website is valid. Therefore you can add a private area where you show the roster and its information based on the api key of the guild leader. To check if the actual user can see the private area, you check the guild status of that user by his own api key.

[HarveyEV]

The authorization required for a website or application to gain access to the secure data should be "grantable" by the GM within game if possible via ranks/permissions. It would be great to have the granularity of "out of game permissions" described above. But in the interim, maybe the GM's API key would suffice.

As for access to the data within the application or website, the authorization should be done within that application or website, and not depend on each users API key. I can imagine the nightmare of having each user generate an API key and have to add it to a field in their web profile.

[ghost]

I think it's best to wait with this update till HoT is released though. It seems like they are making many changes to the Guild System. Influence for example would be outdated.

[lye]

Eh, I'm just leaving influence/merits out for now, I think. There's a lot of data we can expose that probably won't change too much (e.g., roster/ranks/log/etc will probably remain mostly the same).

[HarveyEV]

Agreed. Should revisit after HoT as there will probably more value with Guild Halls, etc.

[Fishrock123]

https://forum-en.guildwars2.com/forum/community/api/Guild-MOTD-API/first#post5729101

Sounds like this will get an update soon.

This seems pretty good. Personally I'm interested in being able to fetch my guild's MOTD. :D

[chutch1122]

As someone who manages a gold & item donation spreadsheet for my guild, it would be incredibly useful if there was an endpoint for getting the guild bank log history and the even guild history log in general.