weblogGroups API Draft
(Tim Bray posted
on the concept of blog groups tonight which motivated me to share this draft which I've had on the backburner for a while. Well, the documentation has been on the backburner. A draft implementation is built and running (See The API, below). Comments welcome... in fact, comments needed... the goal is to gain acceptance across tool makers.)
(Update 2005-1-21 1:54PM: Just heard Dave Winer
talking briefly about groups at the business blog summit. Sent him this link. Will be interesting to see if he has any comment.)
Groups are a way to share weblog entries about a particular topic from many sites in one place. The weblogGroup API is an XML-RPC-based API that enables the concept of groups. We are currently seeking feedback on the concept and hope to generate interest on the part of tool makers and users.
People like to form groups. While many group-based content management systems work very well (bulletin boards, for example), they have one major flaw: content creation is difficult to initiate and sustain. This means that often when content management systems are launched they stagnate. Take the example of a project being run on a bulletin board. Often team members don't feel compelled to stop working on their project and document what they're doing in the bulletin board. The project bulletin board fails to meet the tipping point of content... not enough critical mass.
One of the primary reasons that weblogs create a lot of content is that they are personally-identifiable. People like to become the expert in some arena of life or work. By posting entries over a period of time they build up their value to those who read their sites. This feeds their desire to create more content, which makes them more valuable.
The goal of the weblogGroups project is to merge the fabulous content-creation quality of weblogs with the collaborative nature of groups.
We wanted to develop an approach that allowed people to blog as they normally do and still participate in groups. Here's how it works:
1) Write a blog entry.
2) In your blogging tool, choose the groups that you want to post the entry to.
3) Save and publish your blog entry.
4) A link to your entry is posted to the group.
At its core, a weblogGroup is a collection of links to weblog entries on a particular topic.
The advantage here is twofold. First, the person creating content doesn't have to change the way they do things... they just blog and check a few boxes. Second, even though the person is taking part in a group, the blog entry is posted to their site where they get full credit for it. In other words, the weblogGroups approach doesn't water down the impact of personally-identifiable content creation.
The weblogGroup server then provides a web interface and an RSS feed for each group. In a sense the group is a virtual blog. Interested parties can subscribe to a group or they can subscribe to each writer in the group.
When you blog you often have many interests. But some of those interests are infrequently blogged about. This often creates categories or logs within sites that only have a few entries. weblogGroups allows the writer to post to one blog but have that content separated to many groups at once.
Such a group system needs to span many weblogging tools. People using reger.com and people using MovableType should be able to controbute to the same group. We've developed the weblogGroupsAPI. This API is XML-RPC-based and allows for the creation of groups, posting of entries, searching of entries and a couple other things.
The vision is to have many weblogGroups servers running across the internet. Each blogging tool allows you to subscribe to many weblogGroups servers and makes it easy for you to post your entries to the groups you want to.
We believe this architecture leaves ample room for differentiation and value-add at the tool developer level. We'd like to see the API vetted by others.
=======This API is live and running
at http://www.reger.com/api.log The serverKey (used to list groups, create groups, etc) is "YF6hHlKBX9"
(String searchterms) - Searches titles and descriptions for groups matching search terms. A vector of hashtables. The hashtables contain groupid, groupname, groupdescription, feedurlofgroup, weburlofgroup.
(String groupKey, String entryUrl, String entryTitle, String entryExtract, String author, String authorUrl, int groupid) - Adds a blog post to the group. Returns a random string that is used as a key to remove this entry from the group. Only the person who added the entry should have access to the key.
(int groupid) - A vector of hashtables. The hashtables contain groupid, groupname, groupdescription, feedurlofgroup, weburlofgroup.
(String serverKey, String groupName, String groupDescription, boolean viewingEntriesRequiresGroupKey, boolean addingEntriesRequiresGroupKey) - Create a new group. A valid account on the groups server is required to create a new group.
(String groupAdminKey, int groupid, String groupName, String groupDescription, boolean viewingEntriesRequiresGroupKey, boolean addingEntriesRequiresGroupKey, String newGroupKey, String newGroupAdminKey) - Edits the group.
(String groupKey, int groupid) - Tests the validity of a groupKey.
(String groupAdminKey, int groupid) - Tests the validity of a groupAdminKey.
(String controlKey, String groupAdminKey, String entryUrl, int groupid) - Removes an entry from the group.
- Returns the url where users can sign up for an account that is allowed to add groups.
- Returns the endpoint api url.
Quick API Usage Scenario #1
1) Call weblogGroup.searchGroups("cats") to search for groups on "cats"
2) Post an entry to one of the "cats" groups using weblogGroup.addEntryToGroup(...)... this assumes that you're posting to a group that allows public posting.
3) Use weblogGroup.getGroupDetails(int groupid) to find the rss feed url and/or html url to see your post.
Quick API Usage Scenario #2
1) Call weblogGroup.createGroup(...) to create a group of your choosing. A groupKey and groupAdminKey will be returned... store them.
2) Post an entry to your group using weblogGroup.addEntryToGroup(...)
3) Invite friends by giving out the api endpoint url from weblogGroup.apiEndpointUrl(), the serverKey, the groupId and the groupKey. Reger.com has built-in tools that make it easy to invite friends to groups.
You don't subscribe to a group. We wanted to keep the API lightweight and simple to implement for tool developers. We also wanted to avoid forcing users to create a new set of login credentials for each weblogGroup server that they use.
But we did want to give people who create groups control over content and visibility.
We decided on a key system. Each group has a groupKey and a groupAdminKey. The groupKey grants you access as a user of the group. The groupAdminKey grants you access to the group as an admin. The key itself is simply a random string of letters and numbers.
If you have the groupAdminKey you can define two important properties of a group.
1) Group Read can be set to public or private. A Public Read group can be read by anybody on the internet... anybody without the groupKey. A Private Read group can only be read by people who have the groupKey.
2) Group Post can be set to public or private. A Public Post group can be posted to by anybody. A Private Post group can only be posted to by those with the groupKey.
We understand that this key system is not perfect. If the groupKey is discovered by a party that should not have it the process of comminicating the new groupKey to all members of the group who should have it can be tedious. But it does provide a layer of security and appears to be a reasonable tradeoff between a weblogGroup server that must maintain credentials and one that is completely open. NNTP is a completely open system that works.
We understand that another limitation of the non-subscription system is that you can't go to a group and see who the members are. This is an important feature but, again, one that can be inferred by reading the posts of the group. We wanted to develop a lightweight API to start.
For initial development we opted for simpler schemes that can be adopted by tool makers sooner rather than later. With the proper consensus we could certainly see extending the weblogGroup server to allow for accounts.
Joining the Group
Gaining access and posting to an open (Public Read/Public Post) group is trivial. The user searches on something that interests them (say, triathlons), finds a suitable group and clicks Join. This all happens on the weblogging tool which is making XML-RPC calls to the weblogGroup server.
But how do users get the groupKey so that they can read and/or post to a partially or completely private group? The answer is up to the tool makers. When a group is created, the user who created it is sent the groupKey and the groupAdminKey. They could email the key to others. Or the tool makers could make it easier.
This is how we do it at reger.com: When you create a group it appears in your Groups Tab. You have a shiny Invite button next to it. When you click it you enter email addresses. You check the groups that you want to share. An email is sent with an invitation link. Your friends click that link and either log on or create an account. Once successfully logged-on they are granted access to the group.
For closed groups, the model is based on invitation and exchange of the key. This mimics fairly closely the way that people form secret groups in the real world.
groupKey Requests (not implemented)
This is a possible Requests infrastructure - Somehow allow people without the groupKey to request the groupKey from the Group Admin. This would likely be done with the following API methods:
requestGroupKey(int groupid, String email, String reason);
requestGroupAdminKey(int groupid, String email, String reason);
getListOfOpenRequests(int groupid, String groupAdminKey);
approveRequest(int groupid, String email, String groupAdminKey);
declineRequest(int groupid, String email, String groupAdminKey);
You don't really subscribe to weblogGroup servers in the traditional sense. But at reger.com we've chosen to create that paradigm at the user interface level. To create a group or search for groups you must have the serverKey. The serverKey is valuable because it allows weblogGroup server makers to develop closed group systems... not just closed groups. Of course, at reger.com we want everybody to be able to use the weblogGroup server we have running. So on the UI we auto-subscribe users to the built-in weblogGroup server and grant them the serverKey. This allows them to create groups.
Our vision is that they will also be able to subscribe to many other weblogGroup servers out there. To do this they'll need to enter an API endpoint and a serverKey. That's it.
See It In Action
The best way to see weblogGroups in action is to use our weblogGroups server (note, however, that the API can and should be implemented by other blogging tools/services):
1) Sign up for a free account at http://www.reger.com/ (as soon as others implement you can use their tools too)
2) In your blogging admin tool, go to the Groups tab.
3) Search for and join a group or create a group of your own. There aren't many groups in there right now so you'll likely have to create one.
4) Go back to the admin home and create a weblog entry. At the bottom of the screen you'll see checkboxes for the groups that you can post to. Check one.
5) Save your log entry.
6) View your log entry. It has a link to the groups that it's posted to. You can also go into the Groups tab of your admin tool and view the group that way.
Thanks for any feedback!