Ping!

I wonder if anyone has ever spec'd a piece of software using Blogger.

In this post, I'll take a first stab at web service interfaces that will broker communication between the Ping server and client. I'll probably spend a few 1-2 hour sessions hacking this together over the next couple of weeks. It's gonna be thin at first, and written in pseudospec as I brainstorm.

Here goes... first, a few complex types:

Name: UserProfile
Members: FirstName (string), LastName (string), EmailAddress (string), PhoneNumber (string), DateOfBirth (string), Gender (string), InterestedIn (string), Occupation (string), Company (string), Hometown (string), AboutMe (string), PictureData (binary), TagLine (string)

Name: MACAddrList
Members: [Array of] MacAddr

Name: Locations
Members: [Array of] LocationID (int), LocationName (string), LocationAddress (string), LocationCity (string), LocationState (string), Latitude (float), Longitude (float), Distance (float), Direction (float)

Name: Contacts
Members: [Array of] UserID (int), UserProfile (UserProfile), Distance (float), Direction (float), ContactType (string: "friend", "bookmark", or "friendrequest")

Name: GetUserProfileFriends
Members: [Array of] UserID (int), UserProfile (UserProfile), IsOnline (int)

Now, on to the web service functions:

Name: SignInUser
Inputs: EmailAddress (string, required), Password (string, required)
Output: SessionID (string)
Errors: TBD
Description: Signs a user in, returning a new session id.

Name: SignOutUser
Input: SessionID (string, required)
Output: None
Errors: TBD
Description: Signs a user out.

Name: RegisterUser
Input: UserProfile (UserProfile, required)
Output: None
Errors: TBD
Description: Registers a new user. The EmailAddress, Password, FirstName, and LastName members of the UserProfile are required (a constraint enforced by the RegisterUser() function, not the WSDL).

Name: UpdateUserPassword
Input: SessionID (string, required), CurrentPassword (string, required), NewPassword (string, required)
Output: None
Errors: TBD
Description: Updates a user's password.

Name: UpdateUserProfile
Input: SessionID (string, required), UserProfile (UserProfile, required)
Output: None
Errors: TBD
Description: Updates a user's profile. If members of UserProfile are empty, those elements in the user's profile are not replaced.

Name: SetUserLocation
Input: SessionID (string, required), LocationID (int, required), Latitude (float, optional), Longitude (float, optional), SeenMACAddrs (MACAddrList, optional), CellTowerID (string, optional)
Output: None
Errors: TBD
Description: Updates a user's location. Latitude, Longitude, SeenMACAddrs, and CellTowerID can optionally be provided and are stored for statistical analysis along with the requestor's IP to power GetNearbyLocations.

Name: RegisterLocation
Input: SessionID (string, required), Latitude (float, optional), Longitude (float, optional), LocationName (string, required), LocationAddress (string, optional), LocationCity (string, optional), LocationState (string, optional)
Output: LocationID
Errors: TBD
Description: Registers a new location. One of either the Lat+Long or the Address+City+State must be provided. This constraint is enforced by the RegisterLocation() function, and not by the WSDL. If only an address is provided, the server performs an address->lat/long lookup and stores the results if successful, otherwise an error is returned. Additionally, there should be some out-of-band way to complete location entries with lat/long coords but no addresses.

Name: GetNearbyLocations
Input: SessionID (string, required), Latitude (float, optional), Longitude (float, optional), StreetAddress (string, optional), SeenMACAddrs (MACAddrList, optional) CellTowerID (string, optional)
Output: Locations (Locations)
Errors: TBD
Description: Retrieves a list of nearby locations based on lat/long, a physical street address, a list of MAC addresses of nearby WiFi APs, a cell phone tower ID, and/or the requestor's IP address.

Name: AddOrUpdateContact
Input: SessionID (string, required), ContactUserID (int, optional), ContactEmailAddress (int, optional), ContactType (string, required), NearbyNotifySet (int, required)
Output: None
Errors: TBD
Description: Adds or updates a contact of type "friend' or "bookmark" to a user. One of ContactUserID or ContactEmailAddress must be provided. This constraint is enforced by the AddOrUpdateContact() function and not the WSDL.

Name: DelContact
Input: SessionID (string, required), ContactUserID (int, required), ContactType (int, required)
Output: None
Errors: TBD
Description: Deletes a contact of type "friend" or "bookmark" from a user.

Name: GetContacts
Input: SessionID (string, required), ContactType (string, required)
Output: Contacts (Contacts)
Errors: TBD
Description: Retrieves a user's list of friends, bookmarks, and/or friend requests pending approval. ContactType can be "friend", "bookmark", or "all".

Name: GetUserProfile
Input: SessionID (string, required), UserID (int, required)
Output: UserProfile (UserProfile), LocationName (string), Distance (float), Direction (float), IsOnline (int), GetUserProfileFriends (GetUserProfileFriends)
Errors: TBD
Description: Retrieves a user's profile.

Name: Refresh
Input: SessionID (string, required)
Output: TBD
Errors: TBD
Description: Retrieves queue of state changes that affect the user.

Additional comments:

The key missing piece of information here are complex type definitions (especially around what Refresh() returns). We'll hash these out in the upcoming WSDL file. Most will be similar to the information returned by the mates server (see: mates WSDL). Some additions will need to be made per the Ping mockups. For example, Refresh() will need to include age, gender, and f-o-f information when returning lists of nearby users. [12/18/2005]

Decisions:

- We won't worry about allowing users to anonymously send messages through Ping without revealing their phone numbers. We'll stay focused on our core functionality and rely on the smartphone's SMS, IM, and phone capabilities for communications (for now).

- We won't build out features around pictures (photo album/multiple pictures), locations (driving directions to/from locations), and other functionality that is not new, core functionality in v1.