Keep [C]*(od|do)ing

Sometimes, actually most times, people love exposing, either to attract attention or express affection.

Look how happy they are! This must be enjoyable!

However, one probably should get himself fully covered when it comes to serious business – even it means sacrifice of agility and strength.

This also applies to coding. When one’s code needs to interact with other people’s code or intends to serve as a service, the less exposure, the better. As one of the three pillars of OOP, encapsulation is defined as below:

In computer science, Encapsulation is the hiding of the internal mechanisms and data structures of a software component behind a defined interface, in such a way that users of the component (other pieces of software) only need to know what the component does, and cannot make themselves dependent on the details of how it does it. The purpose is to achieve potential for change: the internal mechanisms of the component can be improved without impact on other components, or the component can be replaced with a different one that supports the same public interface.

Encapsulation also protects the integrity of the component, by preventing users from setting the internal data of the component into an invalid or inconsistent state.

Another benefit of encapsulation is that it reduces system complexity and thus increases robustness, by limiting the interdependencies between software components.

Two weeks ago, I was asked to integrate a third-party online game into our system at work, here is the API I received.

For registration:

http://domain/service/commandHandler.php?Command=doCommand&
RequestID=b5e555ec-7788-486e-8426-37d82a97a287&Code=234ab13&Name=XXXXXXXXX&
Username= XXXXXXXXX&FirstName=NTVA&LastName=NTVA&Password=XXXXXXXX&
Email=XXXXXXXXX&CountryID=2&State=NTVA&PostCode=NTVA&City=NTVA&Address=NTVA&
PhoneNumber=NTVA&GenderID=1&DateOfBirth=20081111&IsAffiliate=FalseDiscountCode=&
BannerID=XXXXXXXXX&IBAN=&BankAccountOwnerName=&SwiftCode=&BankName=

In the manual, it says only parameters marked as XXXXXXX are mandatory, others are all optional. sounds simple!

So here is what I did:

1. Send request like this: http://domain/service/commandHandler.php?Command=doCommand&RequestID=[Guid]&
RequestCode=RandamCode&Name=XXXXXXXXX&Username=XXXXXXXXX&
Password=XXXXXXXX&Email=XXXXXXXXX&
BannerID=XXXXXXXXX.

Response: Error in FirstName, LastName.... blar blar blar.

2. OK I guess it expects every parameter to be passed in even they are optional. So sent request like the below – I would not say it’s dumb:

http://domain/service/commandHandler.php?Command=doCommand&
RequestID=[GUID]&Code=RandomCode&Name=XXXXXXXXX&
Username= XXXXXXXXX&FirstName= &LastName=&Password=XXXXXXXX&Email=XXXXXXXXX&
CountryID=&State=&PostCode=&City=&Address=&PhoneNumber=&GenderID=1&
DateOfBirth=20081111&IsAffiliate=False&DiscountCode=&BannerID=XXXXXXXXX&IBAN=&
BankAccountOwnerName=&SwiftCode=&BankName=

Response: Error in FirstName, LastName... blar blar blar. This time all ‘parameter=’ didn’t complain, but all ‘parameter=NTVA’ failed.

3. After 10 more times try, I finally figured out:

• The RequestCode need to be exact the same value as printed in the API example although there isn’t a single word of explanation about the mythical code.
• All Parameters which have value NTVA in the printed API need to be set to something, if the values are available, you still need to set them to NTVA, NTVA means NULL or empty string.
• The countryCode and GenderID must be numbers and again there is not a single sentence about those being mentioned in the manual. Who cares, let’s pass in the countryCode as 1 (I assure there will be at least one country) and GenderID=1
• The DateOfBirth, you need to pass in a string in ‘yyyymmdd’ format, let’s pass 19800101 to make sure every user I registered can access whatever porn you are going to show…
• Hooray, registration succeeded! But I got no userID?
• Let me give those guys a call to check if I did it right. Then I was astounded by what I heard: the RequestID is not suppose to be unique, just as the magical RequestCode, you need to send the same value (exact as printed in the API) every tim. UserID is not returned with registration command because they can’t see why we need it, but all other commands would return userID so you can get it later if you want – So my assumption is that they don’t know how to return an ID for newly inserted row.

After all these steps, my first thought was to send the API to The Daily WTF.

How hard it could be to check whether a parameter is present in a HTTP request? Is it really impossible to determine if the value of the parameter is empty so I need to pass some stupid string like NTVA?

If things have been done down to such a level, I would not expect them to know encapsulation. (Notice all bold emphasised parts have been violated). But then how could you expect me to send user details into your database? Who knows what the data would end up to? Did you notice there are bank details to be expected?

The contact from the API provider is very enthusiastic about the project. Out of courtesy, I didn’t tell him that the API sucks.

From a tech perspective, I wouldn’t had gave it a go anyway, although the integration was cancelled due to other reasons.

Sometimes, actually most times, you need to get yourself well equipped before going out hunting for business. No one would choose vulnerable partner or hire naked soldiers. In a similar vain, skilled coders would not use overly exposed APIs, which will set everyone in trouble.

Show your robustness, not vulnerabilities.