Basics of API (3): Example & Answer
These are a couple of questions that a technical BA, who is working on an API, may be asked to do. This article explains API specifications, stories, acceptance criteria and UI (user interface) improvements.
The UI currently has the following fields for the destination address:
Deliver a set of requirements suitable to be given to a development team.
Draft a technical specification to describe how to interact with the getaddress.io API.
Draft a technical specification to map out the request/response.
Draft a simple mock-up for any required changes to the UI.
I started by drafting a wireframe for the new interface using Visio:
4) Draft a simple mock-up for any required changes to the UI:
Screen 1: The user is advised to enter their postcode. The “Select address from list” & “Next” buttons are inactive. All green buttons are active.
Screen 2: The user has tapped the “Find my address” button which has enabled the “Select address from list” menu, to enable the user to select. If there is only 1 address associated with the postcode, this step is skipped.
Screen 3: The selected address is pre-populated into a text box and the “Next” button is enabled.
1. Deliver a set of requirements suitable to be given to a development team:
The system must allow the user to enter their postcode
The system must retrieve a list of address for the user to select
The system must pre-populate the address fields with the selected address.
2. Draft a technical specification to describe how to interact with the getaddress.io API:
User Story 1:
As a guest or logged in user, I want to search for my postcode, so that I can easily find my full address.
User Story 2:
As a guest or logged in user, I want to easily find my address, so that I don’t have to manually type my address into the form.
• Provide a POSTCODE field that must contain up to 7 alphabets or numbers.
• On selection of the “Find my address” button, interface with the address server using the getaddress.io API to search the server for addresses that correspond to the Postcode
▪ And multiple addresses are found: Display list of addresses on a drop-down scrollable field. Upon selection of an address, populate the selected address into the Address textbox.
• When an address is selected, enable “Next” button, otherwise, remain inactive/disabled.
▪ And only 1 address is found, populate the found address in the Address textbox.
If unsuccessful, display error message “Address not found”.
• Display “Can’t find address?” link below the “Find my Address” button. On click, launch the user’s browser, and navigate to the Address page of the website.
• Always enable the “Back” button.
3. Draft a technical specification to map out (Describe) the request/response.
On click of the “Find my Address” button, make a call to the Address server through the getaddress.io API (GET method). Using the endpoint “find”, use the data from the postcode field on the UI, to retrieve a list of addresses that correspond with the postcode in the server. Display these addresses on the UI.
Very technical right? LOL- you asked for this!
Anyway, did you notice that I started by answering the last question first? I did so because the question asked that I improve the current user interface (UI), and this was going to affect my technical specification (User Story/Acceptance Criteria). Besides, even if I wasn’t asked to improve the interface, I would have needed to do so, to accommodate the calls to the API, because the current UI does not provide a field to allow the user to select their address, if more than one address is associated with the entered postcode.
As usual, leave your questions and suggestions or contrary opinions.
Author: Nnenna Stevenson, Business Analyst|Product Manager| Enterprise Architect