Latest API Updated on 5/22/09: Download

I have uploaded an updated API with a large number of new methods. The majority of People, Profiles and Groups should be accessible with this API (most of the methods do not work yet, I would love to get some feedback on what is returned as well as some possible new methods before I build everything).

An annoying fact that you may notice in each of the public methods is the fact that every time a web service API method is called the user has to pass their name/password and be authenticated each time (I highly recommend doing this over HTTPS; I will probably look at providing a setting that would require an SSL connection). Due to the fact that JSON-RPC (and other web RPC providers) generally don’t have a concept of cookies, since they are not full web browsers, I cannot use the IIS session state information. At least not that I have figured out.

A later version of the API might interface into the SQL database with its own table to store session state information. Then a single Login method could be provided that would return a session ID to be passed in the LoginCredentials structure instead of a username/password. I really don’t want to mess with that just yet, and as this is an early rendition I don’t expect much overhead from checking the password each time. Each public method also calls the central LoginForCredentials method to perform the actual login, so adding that functionality to that central method would not cause too much of a disruption to the rest of the class.

I began building this initially as an XML-RPC (frankly, I don’t think it would be hard to provide a single core back-end that does the real work and a light front-end that is either JSON-RPC or XML-RPC, or some other RPC style down the road) but switched to JSON-RPC when I realized how much bandwidth would be saved. And when applications for mobile devices start interfacing, every byte counts. A JSON-RPC conversation that searches for a person and then retrieves their information (assuming all I had access to was name and age) might look like this:
-> { "method":"FindPeople", "params": [ { "UserName":"daniel", "Password":"mysecret" } , { "FirstName":"Daniel" , "LastName":"Hazelbaker" } ] }
<- { "result":22 }
-> { "method":"GetPersonInformation", "params":[ { "UserName":"daniel", "Password":"mysecret" }, 22 ] }
<- { "result":{ "PersonID":22, "FirstName":"Daniel", "LastName":"Hazelbaker", "NickName":"Danny" } }

That’s it. Using XML-RPC nearly quadrupled the conversation size. Obviously this specific conversation is pointless since I started with the name, but you get the idea. Honestly, it is actually even less bytes than that since JSON doesn’t normally include any whitespace.

Some Questions…

In what format is PersonCollection.LoadByProfileList?  tag#,tag#,tag# or some other format?

Should Lookups be returned as their descriptive string, or as the lookup ID? Answer: Lookups are returned as a RpcLookup structure that contains the Lookup Value (as a string), Type Id and Value ID.