Basic Rules about the GoPets API

XML

The XML for the GoPets API needs to be well formed. There are a few rules about being well formed, for instance:

• XML documents must contain at least one element.
• XML documents must contain a unique opening and closing tag.
• XML tags are case sensitive.
• Attribute values must be quoted.
• Every start tag must have a matching end tag.
• Tags can't overlap.

Here are some references on the web about XML:

• W3C document on XML
• A tutorial on XML

ID Names and Numbers

There are two unique ways in GoPets of identifying users. There is the user ID (which is text, example : "MeowMeow" and is generally in a UserID field in the XML) and an account number (example : 654984 and is generally in an AccountNo field in the XML). The user ID is picked by the user (though the server asserts that the name is unique) and the account number is picked by the server. Whenever an API call requires returning a unique identifier, it will return both of these to the caller. However, when the caller needs to fill in XML to identify a particular user, she can use either the ID or the number. If both are present, then the API will ignore the account number and use the user ID.

HTTP GET, PUT and DELETE commands

Many of the API commands behave differently depending on whether or not they are called with a GET, PUT or DELETE. For instance, one can get user information using the GET /User/Profile command. One can change user information using the PUT /User/Profile command, however the DELETE command is ignored; the API will not allow a caller to delete a user. With a GET /User/Profile call all information in the User Field is returned. However, with a PUT /User/Profile operation, many fields are ignored even if present; the API will not allow outside callers to modify characteristics that are either assigned by the server or that are unique and validated by the server when the account is set up.

GET operations with array results.

Some API GET commands return arrays; for instance, the GET /Network/Friends command will return all of the calling user's friends. However, some users on GoPets have thousands of friends; putting together an array of that many friends will consume tremendous CPU, memory and bandwidth on the server and take a long time for the client to download. Not to mention that it is extremely unlikely that a caller would actually need thousands of results at once.

To get around this problem the GoPets API will only return so many elements in an array at a time, normally a maximum 10 elements. This provides more than enough information for most user interface requests. Should a caller need less elements or need elements further down in the list, we've provided the ability to page results via query paramters. The caller can use the StartRow and NumRows parameters to control what parts of the array will be returned to it. NumRows can not be more than the maximum for the resource, and if it is not provided then it has a default value of the maximum. StartRow is 0 based (ie the first element has a value of 0). StartRow is allowed to be out of bounds; if it is, no information will be returned. If StartRow is in bounds, but StartRow + NumRows + 1 is out of bounds, then only in bound entries will be returned.

Here's an example on how to return the second set of 10 friend entries:

GET /Network/Friends?StartRow=10&NumRows=10

Having the NumRows=10 parameter is not necessary since the API will, by default, return 10 elements of information in this case.

Additionally, a request can provide the query parameter TotalRows with a value of 1. This will add the total number of elements available in the returned XML. Here we add TotalRows to request the available number of elements:

GET /Network/Friends?StartRow=0&NumRows=10&TotalRows=1

Example Result Fragment

<NetworkFriendsResult>
   <TotalRows>659</TotalRows>
   <Friend>
      <FriendID>Buddy</FriendID>
      <FriendNo>654897</FriendNo>
      <Profile>http://iku.gopetslive.com/UserProfile/UserProfile_654897</Profile>
      <FriendPicture>http://iku.gopetslive.com/UserPortrait/UserPortrait_654897_1.jpg</FriendPicture>
   </Friend>
   ...
</NetworkFriendsResult>

Back to APIDraft