I find that the best way to discuss web service testing is by illustrating a fun and simple example. What could be more fun than a game? So today, we are going show web services by using them to connect a Hangman API to a GUI display. We’ll keep the intelligence in the API, so that the GUI can concentrate on display features.
We’ll begin by figuring out what parameters will need to be passed each way, but before we can do that, we need to identify the kinds of actions that we’ll be communicating (because each could have different parameter needs). The three kinds of actions we’ll need to account for are starting a new session, starting a new game, and continuing guesses in a game.
When we try to start a new session, we send out a simple request for a new session. We either get a session ID or a failure. Each session ID is a 10-character string. If the API has the maximum number of sessions, the API responds with a -1 instead of the session ID to indicate a failure. If it fails, you can press a button in the GUI to try again to start a new session, with the same possible responses as just listed. The user will never see this session ID; it will just be used by the GUI for future test soap web service calls to the API. Once we get a session ID, we can proceed to starting a new game.
To start a new game, the user will be asked if they want an easy game, a hard game, or to quit (each on a separate button). The GUI will also display the number of won, lost and played games so far. Each unguessed letter will be a button in the GUI, so we don’t have to worry about error-checking for re-guessed letters or things other than a single ‘A’ through ‘Z’ character. Each button will send a single parameter (the letter) to the API along with the session ID. A Quit button and the X in the upper right corner of the GUI will both allow the user to tell the API to kill the current session. Otherwise, the GUI refreshes, displays the alphabetic string of wrong letters guessed so far (which is empty when the game begins), clears the Hangman picture, and requests a new game using the easy/hard determination as a request parameter, along with sending the session ID. The API responds with a string of _’s which are the Hangman pattern of the new game, and the GUI displays the pattern. Also, “Games Won”, “Games Lost” and Games Played” all display followed by 0’s.
To minimize error-checking, the GUI displays a button for each unguessed letter. The user can either select a letter button or X out in the upper right corner to end the session (as we detailed in the previous paragraph). The GUI sends a request to the API consisting of the session ID and the guessed letter. The API responds with the session ID, the guessed answer string (which will now includes occurrence(s) of the guessed letter if found), and a string of wrong guesses sorted alphabetically. The GUI accepts the response, displays the wrong guesses string, and updates the Hangman diagram based on the length of the wrong guesses string. The GUI then refreshes the letter selection button list, listing each letter alphabetically that does not appear in the guessed answer string or the wrong letters string. The Hangman diagram, based on the number of wrong guesses, consists of a noose (which appears even if the string is empty), a head, a neck, a body, two arms and two legs. Each limb is two pieces for an easy game, and one piece for a hard game.
After each guess, the GUI returns you to the previous paragraph for guessing new letters, unless one of following 3 things happens. First, the user could X out in the upper right of the GUI (we’ve already discussed this option). Second, the entire answer could be guessed correctly, which we’ll be able to see because the response from the API will have a guessed answer string with no _’s in it. If this happens, a happy animation appears where the noose disappears, the person fills in completely then dances a little jig (with music), and “Games Played” and “Games Won” display numbers incremented by 1 in a dramatic fashion. Lastly, the player could get hanged which we’ll be able to see because the wrong letter list reaches a length of 7 (for a hard game) or 11 (for an easy game). If this happens, an animation shows the person swinging back and forth on the noose while Taps plays in the background, and “Games Played” and “Games Lost” display numbers incremented by 1 in a dramatic fashion. After a win or a loss, the user is returned to starting a new game, back up at the fourth paragraph of this article.
I hope you have enjoyed reading this example about how web services communicate in the API development world, and the importance of knowing the parameter structure for the requests and responses that occur between the digital entities that fill this ecosystem.
