Thursday, October 04, 2007

What Would You Do with SunWikis Remote API?

As I mentioned previously, one of the features for that I'm working on is opening up the remote API. Before we do so, we need to customize the current behavior in order to make it a bit more secure. Before the feature is in production, I'd like to know how you would like to use it, so that we can factor that in, while customizing it.

The main problem with the remote API right now is that it is either on or off. There is nothing in between. Because the remote API is very powerful (you can do everything that you could do via the browser and more), we'd like to limit who can use it in order to avoid having to clean up the mess created by reckless or malicious clients. Right now we are thinking about limiting the client IP addresses that can connect to the remote API, and/or limit the access to the service based on user's group memberships or user account permissions.

I'd like to get a better understanding of if and how would you use the remote API for, so that we can provide you with the best solution that fits needs of the majority.

Some use cases that come to mind are:
  • use an existing command line client to access SunWikis
  • a (command line) tool that takes your data in some (XML) format, transforms it to our wiki markup and uploads it to your space
  • an application that creates an XYZ report from your database, build server, or other data source and publishes it in a wiki space every night at 3am
  • wikification of an existing application a la JDocs
Feel free to come up with another (crazy) idea and let me know about it (leave a comment on my blog or send an email to our mailing list (internal only)).

For those who want the technical details:

Each approach of limiting the access that I mentioned above has it's pros and cons. IP address restrictions are suitable for the integration of SunWikis with another web application or web service. On the other hand, it won't work well if the remote API is being accessed from your notebook or desktop that doesn't have a stable IP address.

The restrictions based on group memberships (e.g. only Sun employees can access the API) are very well suited for personal use (e.g. the uploading multiple wiki pages or the renaming of wiki pages in batches), but won't work for web application integration, because employees would have to include their passwords in these applications, which is not a smart thing.

Another problem with both of the previous approaches is that a bug in a client could affect content in all the wiki spaces, because Sun employees have write access to all spaces by default.

A compromise might be to:
  1. let a user create special account used only for remote access
  2. add this account to a special group (would be automated)
  3. grant write access to this account on a per-space basis (requires space admin intervention - the same as how permissions are being granted to external users)
This way a space admin (a Sun employee), has to endorse such an account (by granting it the write permission). In addition to that, this account will have access only to this space or maybe a few other spaces (if it is granted access to more spaces), which limits the potential damage.

Maybe there is another way to let trust-worthy folks use the remote API - if you know about something, let me now. ;-)

If you can't wait to start using or even writing clients for SunWikis, Atlassian has some good Confluence documentation that might be interesting for you if you have big remote API plans. Most importantly check out the Remote API Specification. Other interesting stuff: Remote API Examples, Confluence SOAP Client in Java


Danny Holland said...

Would a remote API allow for some automation of page and content creation? Pull information from an email alias to a wiki page. The other question I have is a remote API allow use of a application similar to blogs or twitter? Thanks

Igor Minar said...

Would a remote API allow for some automation of page and content creation?

Absolutely, with the remote API you can pragmatically access That means that you can write programs that access SunWikis and do whatever you program it to do.

If you are not into programming, there is a good chance that you'll be able to use an existing Confluence client or if someone writes something in the future and shares it with others, you'll be able to use it as well.

The other question I have is a remote API allow use of a application similar to blogs or twitter?

Yes, both and already have a remote API that others can use. In case of twitter, the authors claim that most of the traffic comes through the remote API! (e.g. IM clients, widgets, mashups etc)

Anonymous said...

enabling the API is in part to allow for uses that we *can't* predict right now. so rather than trying to figure out possible use cases, i'd rather focus on what we don't want to allow (i.e. access to non-sun employees initially) and call it good. build a better mouse trap...

Igor Minar said...

The thing is that there are some users that already know how they want to use the remote API. So the point is to make sure that we don't do something that will make these use cases impossible.

Regarding the access for Sun employees only - I don't agree with that. We discussed this at our team meeting this week and all of us agreed that the segregation between Sun employees and external users should be minimal or none (where appropriate).

Having said that, we are not going to give external users access to do anything they want. Users will need endorsement by space admins and even then the privileges for the remote API access will match those in the regular web interface.

Anonymous said...

Well, I was going to propose that only Sun employees have such access to Sun Wikis, but since you all have agreed that segregating Sun Wikis is not the way to go, then I'd say open the remote API up to everyone, depending on the security allowed by the admin. Here here!

I would use the Remote API plugin to upload files that I've converted from SGML. For example, the Sun Cluster group has decided to make the Release Notes Supplement, which we discontinued on in our last release due to resource constraints, available on the Sun Cluster Wiki. I now must actually cut and paste the content into the Wiki, a process that is prone to error. Having the Remote API plugin would make his process oh so much easier, more efficient, and less prone to error.