4/2/2020 TMA 03: View as single page
https://learn2.open.ac.uk/mod/oucontent/view.php?id=1600344&printable=1 1/17
TMA 03 Printable page generated Thursday, 2 Apr 2020, 06:36
TMA 03
Submitting your work
This tutor-marked assignment (TM352 TMA 03) must be submitted by 12 noon (UK local time) on 23 April 2020.
If you foresee any difficulty with submitting your assignment on time, you should contact your tutor well in advance of the
cut-off date.
This module requires all assignments to be submitted electronically. To submit an assignment, please follow the link(s)
provided from your StudentHome page to the online TMA/EMA service.
This tutor-marked assignment will make up a third of your continuous assessment score for this module. For more details
about how your score for this module is calculated, see the Module Guide.
For further information about policy, procedure and general submission of assignments, please refer to the Assessment
Handbook, which can also be accessed via your StudentHome page.
Your answers to this TMA will be in the form of a written Solution Document, which needs to be zipped together with
images and code
If you need further guidance on any assignment questions, please ask your tutor who will be happy to help.
Your tutor will mark your work and send it back to the online TMA/EMA service for you to pick up. You can find guidance
on using the online TMA/EMA service via StudentHome.
You should put your name, your personal identifier, the module code, the assignment number and the date on the title
page of your report. It is also useful to your tutor if you include this information as part of the header or footer.
Plagiarism and collusion
It is imperative that you avoid plagiarism, as it is a form of cheating. If you do plagiarise, then you won’t simply lose
marks: instead, your work will be referred for further disciplinary action. If you are in any doubt as to what constitutes
plagiarism, please refer to the University guidelines or see the Module Guide.
The work you submit must be your own. By all means discuss ideas and share the results of searches with other
students, but work copied from or produced jointly with others is not acceptable.
Introduction
In Block 3 you encountered a taxi-sharing app, the scenario for which is briefly summarised below.
Taxi-sharing app scenario
A large number of people work at the Open University campus in Milton Keynes, with many of them travelling
between the train station and the campus. The university provides a shuttle bus at peak hours, but outside these
hours the options are reduced. To travel to and from the campus, you either take a taxi (which is costly), or you try to
catch a local bus that takes longer and is less frequent. Is there a mobile app that would allow users travelling to the
Open University campus to share a taxi?
4/2/2020 TMA 03: View as single page
https://learn2.open.ac.uk/mod/oucontent/view.php?id=1600344&printable=1 2/17
There are four parts in this TMA:
Questions 1–3 apply what you have learnt from Block 3 to create a mobile app that draws on the taxi-sharing
scenario discussed at the beginning of the block.
Question 4 asks you to come up with a new application relevant to you, and to carry out some market research and
apply what you have learnt.
If you are not able to complete every task you should do as much of it as possible, and include any code have written in
your Solution Document, since any parts that are correct will still earn you some marks.
Question 1 The user interface for a taxi-sharing app (25 marks)
For this part, you should only be concerned with the presentational layer of the proposed mobile app, i.e. primarily its
graphical user interface (GUI). This is similar to the activities you have completed in Block 3 Part 5. For a Cordova app, the
GUI will be implemented by a single HTML page, with calls from the interface elements (such as buttons) to the business
logic implemented by the JavaScript functions you will go on to implement in Question 2.
Table 1: Basic functional requirements of the app
List five additional functional requirements (FRs) for the proposed app different to those proposed above following
the format for functional requirements in Table 2 of Block 3 Part 5. You may suggest any functional requirement that
is relevant to an application which allows people to share a taxi ride.
For each functional requirement, state a unique obstacle that the developer will have to consider. Each obstacle
could be a technical or non-technical condition that makes implementing the functional requirement difficult or
impossible. In other words, a functional requirement is a task we want the app to carry out for the user and an
obstacle is something we can think of that might stop it from working.
Only brief answers are required: one or two sentences for each functional requirement, and one or two more for each
obstacle.
(10 marks)
a. Functional requirements and obstacles to fulfil them
The basic requirements of the application have been defined as follows.
The application should allow a member of university staff to either share a taxi they will book (an offer) or request a
taxi to share that another staff member has booked (a request). Taxis may be shared either from the train station in
Milton Keynes to travel to the campus, or vice versa. As the destination is always known only the pick-up address is
stored.
These are summarised in Table 1 below.
FR Name Description Obstacle
FR1 Register
and
request
The app shall register, offer, request and cancel taxi-sharing for
an employee with a valid OUCU.
The user may not have a valid
OUCU.
FR2 Match For an employee, the app shall list available matching taxi
locations on a map.
The GPS signal may not be available
if the user is in a building.
FR3 Notify
matches
For an employee, the app shall notify (on request) the user
when a taxi offer or a taxi request is available.
There are no other users of the app.
b. Interface elements
4/2/2020 TMA 03: View as single page
https://learn2.open.ac.uk/mod/oucontent/view.php?id=1600344&printable=1 3/17
Save a copy of the provided project tm352-tma03-skeleton. In this project, the file www/index.html is an
incomplete skeleton of a form that fulfils the following five functional requirements that expand on FR1 and FR2.
A user should be able to:
1. Register to use the taxi-sharing service using their Open University Computer Username (OUCU) e.g. ‘abc123’.
2. Offer to share a ride by specifying when the car will be available in the offer, i.e. starting time plus the duration
of the period that they are prepared to wait. The pick-up address of the sharing offer also needs to be specified
as a string, e.g. ‘Milton Keynes Central station’, or ‘Open University campus’.
3. Request to share a ride by specifying the time when the ride is needed as a time stamp, i.e. starting time and
the address to pick up from.
4. Cancel all offers or requests associated with their OUCU.
5. Request that the map will be updated with the offers or requests at regular intervals.
6. Request that the map will not be updated with the offers or requests.
Add graphical user interface elements (that is, controls such as input fields and buttons) to the HTML page in order to
support the six functional requirements above. It is up to you to select whichever HTML elements you think are most
relevant; you may reuse elements to fulfil different requirements. It is expected that all the elements will be visible at
all times. The interface should fit within a single screen without scrolling, but no CSS styling is required in your
answer. You are not required to validate the input.
Each element should have all appropriate parameters specified, such that the file is complete and ready to work
when combined with the JavaScript that you will complete in Question 2.
In the index.html skeleton file you will find comments below, indicating where to place these GUI elements:
TODO: add text and form entry methods to capture relevant details.
TODO: add buttons to allow the various functional requirements to be enacted.
When you have done this, copy the body of www/index.html into your Solution Document, highlighting the changes
you have made. Include it in your zip file using the file name index_1b.html.
(10 marks)
c. Map canvas
Add a div for a map, where indicated by the following comment in the skeleton.
This element should have all appropriate parameters specified, such that the file is complete and ready to work when
combined with the JavaScript that you will complete in Question 2.
Later in Question 2 you will implement the mapping functionality fully; for now this is just a placeholder that will
appear empty on the page.
Build your project with the cordova commands and examine the user interface elements and layout on an Android
device, emulator or browser following the instructions in given in Block 3.
To complete this question, you must take a screenshot of the running app either on an Android device, the emulator,
or running on Google Chrome. You must display the buttons and make the interface elements visible. The aesthetics
of the look and feel of the layout are unimportant (you do not need to style the web page with css), but do make good
use of the space available to ensure that the elements appear on a single screen.
Copy the body of www/index.html into your Solution Document and include it in your zip file using the file name
index_1c.html. In your zip file you should also include one screenshot of the running mobile app showing the user
interface; use the file name screenshot_1c.png.
<!—TODO add a placeholder for the HERE –>
4/2/2020 TMA 03: View as single page
https://learn2.open.ac.uk/mod/oucontent/view.php?id=1600344&printable=1 4/17
The exact sequence of keys to capture a screenshot is specific to every Android device, but typically involves
pressing the power and volume buttons at the same time. Once captured, the screenshot image is typically saved in
/storage/sdcard0 under the subfolder Pictures/Screenshot (or DCIM/Screenshot depending on the device).
The name of the file is typically ‘Screenshot_YYYYMMDD-XXXXXX.png’. Rename the file screenshot_1c.png so it
is clear that the screenshot is made for this part of this question. If you have any difficulty in creating a screenshot,
then you may submit a photo of the screen instead.
(5 marks)
Question 2 Business logic for the mobile web app (20 marks)
This question is concerned with implementing parts of the business logic for the proposed taxi-sharing app, so that it can
be deployed as a Cordova app on an Android device.
To support you with this question, we have provided a REST API which will handle all the persistence and storage required
for the taxi-sharing app.
To answer this question you will implement the functional requirements outlined below.
As you implement each functional requirement, copy the code in www/js/index.js that you have written for that
requirement into your Solution Document and include it in your zip file using the file name index_2.js. You should
include a screenshot of the running app and name it screenshot_2.png.
Functional requirements
The functional requirements (FR) for this app are described as follows. FR1.1, 1.4, and 3 have already been implemented
in the skeleton project (see www/js/index.js), while the places to implement other functional requirements are indicated
by TODO comments. Please do not remove these comments as your tutor will locate them to check your code. You need
do no further work on FR1.1, 1.4 and 3. You may draw on these provided solutions to help develop your own solutions to
the remaining functional requirements.
You may instead implement all the FR in your own code (that is you do not need to use the provided skeleton, but instead
start from scratch), if you do this please comment your code with appropriate TODO comments to identify clearly where
each FR is implemented.
FR1. The app shall register, offer, request and cancel taxi-sharing for an employee with a valid OUCU. This functional
requirement is further refined into four sub-requirements:
FR1.1 Registering a user’s OUCU
FR1.2 Offering a taxi for a duration of availability with a pick-up address, starting time and duration (in hours) for
which the offering user is prepared to wait using the taxi/orders API
FR1.3 Requesting a taxi at a pick-up address for a specific time using the taxi/orders API
FR1.4 Cancelling all taxi orders by deleting all existing orders (offers and requests) associated with an OUCU.
FR2. For an employee, the app shall show all available matching taxi locations on a map. This functional requirement has
been refined into two sub-requirements:
FR2.1 The matching taxis should be found via the matches API, then for each
FR2.2 The map location should be found via the OpenStreetMap API and then location of the match shown on the
map.
FR3. For an employee, the app shall notify (on request) the user when a taxi offer or a taxi request is available.
There is no need to validate information provided by the user, however you should correctly handle any errors reported by
the APIs you call and report these in a meaningful way to the user.
Taxi Sharing REST API
4/2/2020 TMA 03: View as single page
https://learn2.open.ac.uk/mod/oucontent/view.php?id=1600344&printable=1 5/17
This is a REST API that handles HTTP requests with GET, POST or DELETE operation types on an end-point URL.
The URL for the API has an IP address of:
If it is necessary for the module team to change this IP address, then the new IP address will be publicised in the TM352
Block 3 Software support forum . Check the forum if calls to the API fail or before starting work on this TMA.
137.108.92.9
taxi/orders API
The taxi_orders endpoint is writable so that it is possible to create and save new records in the application. When
creating a new record, the server will generate the ID value so this should not be passed to the API.
For the taxi_orders endpoint it is possible to perform GET, POST and DELETE operations. These are described below,
and we have also provided a Postman collection that allows you experiment easily with the API. Details of the collection
are in the appendix.
GET
GET always requires an OUCU to be supplied, but an ID is optional. GET with no ID will retrieve all the orders for the
OUCU. GET with an ID value will retrieve just the single record matching the ID if it also matches the supplied OUCU. If an
ID is provided and there is no matching record then an error is returned. A successful GET with an ID returns the record
with that ID. For example, the GET request
will return the order record with an ID value of 110919:
In this example, the type ‘1’ indicates it is a ‘request’ record, hence the ‘end’ time is unspecified (as a ‘null’ value). For the
type ‘0’ records, the ‘end’ time will need to be specified for the API call, and this value should derive from ‘start time +
duration’ using computation in JavaScript from the inputs provided by the user in the HTML form.
http://137.108.92.9/openstack/taxi/orders/110919?oucu=<OUCU>
“status”: “success”,
“data”: [
“id”: “110919”,
“start”: “2018-12-05 18:09:00”,
“end”: null,
“type”: “1”,
“address”: “Open University”
]
P
OST
POST will create a new record. The record should have appropriate values for the fields (oucu, type, address, start
and end) but no ID should be passed to the API because the server will generate a new unique ID value for the record.
The address is the location where the taxi will pick up the riders. The value of OUCU is your OUCU. The value of type is 0
for an order or 1 for a request. The start and end values are datetime (e.g. ”2018-12-05 18:09:00”), and end is required
only when type is 0.
A POST
with additional body elements, e.g.
http://137.108.92.9/openstack/taxi/orders
4/2/2020 TMA 03: View as single page
https://learn2.open.ac.uk/mod/oucontent/view.php?id=1600344&printable=1 6/17
can be sent to the API (these parameters should be provided as form-data) to return a success message and the new
record, including the generated ID.
If the values are not appropriate for the database fields then an error will be returned.
OUCU=<OUCU>
type=1
address=”Open University”
start=”2018-12-05 18:09:00”
DELETE
A DELETE will remove a single record from the server. The unique ID of the record must be provided. To DELETE an
order with an ID value of 110919, the following call can be made:
This will return a message (if the record exists):
http://137.108.92.9/openstack/taxi/orders/110919?oucu=<oucu>
“status” : “success”
taxi_matches API
A taxi_matches record represents a matching pair of an order and a request. The API only provides the GET operation.
To retrieve all the matching pairs belonging to user’s OUCU we can use the following GET:
which returns, for example:
Note that the word ‘hire’ is used instead of ‘request’.
http://137.108.92.9/openstack/taxi/matches?OUCU=<OUCU>
“status”: “success”,
“data”: [
“start”: “2018-12-05 18:12:00”,
“hire_oucu”: “<OUCU1>”,
“hire_address”: “Open University”,
“offer_oucu”: “<OUCU2>”,
“offer_address”: “Open University”
,
“start”: “2018-12-05 18:09:00”,
“hire_oucu”: “<OUCU1>”,
“hire_address”: “Open University”,
“offer_oucu”: “<OUCU2>”,
“offer_address”: “Open University”
]
M
ashing up with OpenStreetMap REST API
Since the orders API only defines the location of the orders/requests by a street name, to display the geolocation on the
map you need to translate these street names to geolocations, which are represented by latitude and longitude pairs.
4/2/2020 TMA 03: View as single page
https://learn2.open.ac.uk/mod/oucontent/view.php?id=1600344&printable=1 7/17
Since HERE Maps does not provide a REST API for this purpose, we will use another REST service, that from
OpenStreetMap.
The URL end-point of the OpenStreetMap is typically:
http://nominatim.openstreetmap.org/search/<ADDRESS>?format=json&countrycode=gb
where you can fill in the URL by the ‘address’ for which you want to look up the geolocation.
Note that if your application repeatedly calls this URL in a short space of time, then your access to the API will be
automatically blocked for a period. So if your code suddenly stops working this is the most likely cause. Double-check the
number of calls your code is making and find an appropriate way to restrict them. Whilst debugging other parts of your
code it can be beneficial to temporarily replace the call to OpenStreetMap with a hard-coded value.
Using either GET or POST HTTP requests, you should be able to receive a response in JSON format, e.g.
Note that you only need the values of the ‘lat’ and ‘lon’ attributes to be able to mark on the map.
As you implement each functional requirement, copy the code in www/js/index.js that you have written for that
requirement into your Solution Document and include it in your zip file using the file name index_2.js. You should
include a screenshot of the running app and name it screenshot_2.png.
[
“place_id”: “87493083”,
“licence”: “Data © OpenStreetMap contributors, ODbL 1.0. https://osm.org/copyright”,
“osm_type”: “way”,
“osm_id”: “44106237”,
“boundingbox”: [
“52.020797”,
“52.0281706”,
“-0.7155217”,
“-0.7032044”
],
“lat”: “52.02453775”,
“lon”: “-0.709274809394501”,
“display_name”: “The Open University, Walton Drive, Walton, Monkston, Milton Keynes, South East, England, MK7 6AA
“class”: “amenity”,
“type”: “university”,
“importance”: 0.692186908444,
“icon”: “https://nominatim.openstreetmap.org/images/mapicons/education_university.p.20.png”
,
…
] I
mplementation overview
Registration is completed by storing the value from a text field into the users list via the ‘users’ API.
Next a user enters field data for an offer (type=0) or request (type=1) for a taxi. When a button is pressed the record
should be stored and the map updated (or if the map is periodically updated anyway by a timer, it can be left to update
automatically).
To update the map the matching records are found from a call to the ‘matches’ API with the user’s OUCU. The OUCU for
this could be stored or obtained again from the interface. From the matches API call we get a list of pairs where one
OUCU is the users (for an offer or request) and the other half of the pair gives the other user’s OUCU (for the matching
request or offer).
4/2/2020 TMA 03: View as single page
https://learn2.open.ac.uk/mod/oucontent/view.php?id=1600344&printable=1 8/17
For example if my OUCU is ‘OUCU1’ then I might get back: “status”: “success”, “data”: [ “start”: “2018‐12‐05 18:12:00”,
“hire_oucu”: “<OUCU1>”, “hire_address”: “Open University”, “offer_oucu”: “<OUCU2>”, “offer_address”: “Open University”
, “start”: “2018‐12‐05 18:09:00”, “hire_oucu”: “<OUCU1>”, “hire_address”: ” Open University”, “offer_oucu”: “<OUCU3>”,
“offer_address”: ” Open University” ]
The matching record pairs each have the same address as one of the user’s posts but will have been checked for the
given OUCU, time and type to be a match. In the records there are the address location and a start time. Using these
records locations of the matching offers or requests can be plotted. The map can be centred on the first such matching
pair and other pairs can be marked on the map (they may not be shown if too far from the centre).
To delete a user’s records their OUCU is needed from a field or from a record they made in an offer/request.
Hint: For the implementation of FR2.2, you can adapt the code from Activity 13 in Block 3 Part 5 by positioning the
geolocation markers on the latitude/longitude obtained from the GET method of the third-party OpenStreetMap REST
service.
Question 3 Using a plugin (20 marks)
In this question, you will explore the possibility of enhancing the functionality of the taxi-sharing app by the use of Cordova
plugins. Note that it is possible to earn marks in this question even if you were not successful in getting all the features to
work in Question 2. This question builds your study of Block 3 Part 5.
a. Research
Select one of your additional Functional Requirements from Question 1(a) that could be enhanced with the aid of a
Cordova plugin. Do some brief market research to provide evidence in the form of a feature table that demonstrates
that the enhancement you propose is useful.
Record the market evidence you have found (3 marks) and describe the proposed solution (3 marks) for the
enhancement.
(6 marks – around 200 words)
b. Select a Cordova plugin
Document the process of selecting a suitable plugin in no more than 50 words (2 marks), describing what possibilities
you considered that could help implement your solution and the choice you made in no more than 50 words
(2 marks). Finally, explain the reasons for your decision in no more than 100 words (2 marks) .
(6 marks – 200 words)
c. Implement coding
Write the code that would be needed to implement the new feature to the existing taxi-sharing app. Include the code
in your Solution Document and include index_3.html and index_3.js in your zip file (3 marks), along with an
explanation in your Solution Document of how the code works (around 100 words, 2 marks) and how the user would
use the feature (around 100 words, 1 mark).
Note that you can get the marks for the explanation even if you are unsuccessful in getting the code to run; in this
case, document what you tried in order to get the code to work and the obstacle that you could not overcome.
(6 marks – 200 words aside from code)
d. Build and test your project
Build your project and then test the app. You can get marks for this part even if the build fails.
Explain briefly whether or not the app worked as expected in no more than 50 words (up to 1 mark) and list any
problems you observed in no more than 100 words (up to 1 mark). Include a screenshot with the file name
screenshot_3.png in your zip file.
(2 marks – 150 words)
4/2/2020 TMA 03: View as single page
https://learn2.open.ac.uk/mod/oucontent/view.php?id=1600344&printable=1 9/17
Question 4 Invent a possible app (35 marks)
In this question you are asked to think of your own idea for a possible mobile app that might be relevant to you. For
instance, can it help with your daily life, your work, your study, or your other needs? Investigate where it could fit into the
marketplace (i.e. would it satisfy other users who have similar needs to you; estimate how many users would need it, how
frequently someone would need to use it, etc.). Carry out an initial analysis of requirements (what features or
functionalities it entails), and do some informal market research (are there already similar apps with the same
functionality? If ‘yes’, can you do better in terms of some measurable quality attributes?).
The question is based mainly on Sections 3.1 and 3.2 of Block 3 Part 5. Note that you are not asked to write any code in
this question.
a. Identifying a market gap
Spend a little time thinking of an idea for a potential app. Then investigate the Android app marketplace for similar
apps and create a feature table to look for any gaps that could be filled by the app you design. Show that you have a
combination of features not found in any other app.
(5 marks – 100 words)
b. App functional requirements
Having identified the market gap, draw up a list of five functional requirements for your app – use a table with each
row describing one functional requirement and obstacle. If you are struggling to identify five requirements then try
breaking down a large requirement into several smaller ones.
(10 marks – 200 words)
c. App description
Write a description of your app intended for use on an app store. Use no more than five sentences to tell potential
purchasers the purpose of your app and what features it offers. Such a description would be normally the first
paragraph shown in an app store, so try to be brief, yet informative and attractive. Your potential users would like to
purchase it by knowing that it has some value (e.g. saving them trouble, providing useful information, allowing them
to be more productive, helping them get things done, or providing entertainment, etc.).
(5 marks – 100 words)
d. App wireframe
Sketch a wireframe of your app’s user interface as an image file wireframe_4d.png. The image could include
several screens if necessary. This does not have to be a finished or polished design – just a rough initial draft. You
can produce it in any way you like: you might use a software drawing program of your choice, or simply sketch it on
paper and scan or photograph the result.
The key thing is to annotate this sketch to show where interactions need to happen (e.g. buttons), what information is
to be shown (areas or regions), and for the functionality described in your answers to Parts (a), (b) and (c). This
should demonstrate how all the functional requirements are met.
(8 marks)
e. Market investigation
Carry out short interviews with two or more potential users – either face-to-face or electronically – to discover if they
would consider purchasing the app, having seen its description and the mock-up of its interface. These could be
other students, friends or family members.
In your Solution Document include two short quotes, from different interviewees, to illustrate what feedback they gave
on your app (2 marks, around 50 words) and also specifically collect feedback on how the app met its proposed
functionality by discussing sample inputs, outputs, or the steps the users followed when interacting with the
wireframe (4 marks, around 100 words). Say whether or not the response to your app was broadly favourable
(1 mark, around 50 words).
4/2/2020 TMA 03: View as single page
https://learn2.open.ac.uk/mod/oucontent/view.php?id=1600344&printable=1 10/17
(7 marks – 200 words)
What to submit
When you have completed the TMA, you need to submit your assignment as a single file called TMA03.zip to the online
TMA/EMA service.
Your Solution Document will comprise a written report, which should be a file that can be opened in Microsoft Word. Your
zipped TMA file will also contain source code and screenshot images as indicated above, but must be no larger than
10 MB in size. If your zip file is bigger than this, you should reduce the size of the images you have collected in order to
reduce the overall size of the zip file.
You should put your name, your personal identifier, the module code, the assignment number and the date on the title
page of your report. It is also useful to your tutor if you include this information as part of the header or footer in your
report.
Checklist of submission files
index_1b.html
index_1c.html
screenshot_1c.png
index_2.js
screenshot_2.png
index_3.html
index_3.js
screenshot_3.png
wireframe_4d.png
Your Solution Document (.doc or .docx) for Questions 1(a), 3(a), 3(b), 3(c), 3(d), 4(a), 4(b), 4(c) and 4(e)
(1500 words)
Breakdown of marks
Question 1 (25 marks)
Question 2 (20 marks)
index_2.js
screenshot_2.png
Question 3 (20 marks)
a. Functional requirements (10 marks, 200 words)
b. Interface (10 marks)
index_1b.html
c. Canvas (5 marks)
index_1c.html
screenshot_1c.png
4/2/2020 TMA 03: View as single page
https://learn2.open.ac.uk/mod/oucontent/view.php?id=1600344&printable=1 11/17
Question 4 (35 marks)
a. Research (6 marks, 200 words)
b. Select a Cordova plugin (6 marks, 200 words)
c. Documenting the implementation code (6 marks, 200 words aside from code)
index_3.html
index_3.js
d. Build and test your project (2 marks, 150 words)
screenshot_3.png
a. Identifying a market gap (5 marks, 100 words)
b. App function requirements (10 marks 200 words)
c. App description (5 marks, 100 words)
d. App wireframe (8 marks)
wireframe_4d.png
e. Market investigation (7 marks, 200 words)
Appendix
Using Postman to explore the API
Download and install Postman from:
https://www.getpostman.com/downloads/
Skip creating an account. Click on the import button and import the supplied file “TMA03_API_TEST” from the resources
page, open the collection in the sidebar and click on a request to experiment with it. You should edit the request to replace
cdt54 with your own OUCU.
Question 2: Database and API implementation details
The data for the API is stored in a database. We describe the structure of the database here to help you understand how
to use the API effectively. The database has a single table taxi_orders which represents the core data of taxi
orders/requests.
The taxi_orders database table
Each row of the taxi_orders table represents an order or a request. The table has six columns, which are listed below
with their types.
id int(11) /* unique identifier of this record */
oucu text /* the OUCU id */
start datetime /* the starting time */
end datetime /* the ending time */
type int(1) /* type of the record, 0 = offer, 1 = request */
address text /* address in string */
4/2/2020 TMA 03: View as single page
https://learn2.open.ac.uk/mod/oucontent/view.php?id=1600344&printable=1 12/17
The id is a unique number which is of type auto_increment so that it is assigned by the system as a unique number
when a row is added to the table. So in creating a new record you need to provide a oucu, a start date and an address,
which specify the time and place that an order (type = 0) or a request (type = 1) was made. If it is an order, additionally
an end date also needs to be specified for the API call, which you should derived from ‘start date + duration’ provided in
the user interface.
In the above example of records in the table, ‘user1’ offers a ride at ‘Walton Hall, MK7 6AA’ from ‘2018-12-05 18:09’
until ‘2018-12-05 19:09’, whilst a bit later, ‘user2’ requests a ride on ‘2018-12-05 18:39’ at the same address. Since
the request start time of user2 is well within the offer of user1, the system can tell that there is a ‘match’. The REST API for
basic queries on the orders table is shown below.
id oucu address start end type
1 user1 Walton Hall, MK7 6AA 2018-12-05 18:09:00 2018-12-05 19:09:00 0
2 user2 Walton Hall, MK7 6AA 2018-12-05 18:39:00 null 1
The REST API
The database sits behind a REST API coded in PHP. This allows access to the database tables in terms of saving or
retrieving data for presentation.
In general, REST HTTP operations are used to access data as outlined in the table below. Note that the ‘POST’, ‘UPDATE’
and ‘DELETE’ operations are not available to derived views.
Each table/view has a corresponding URL as part of the API, which is used to access the table:
In calling the API, each base URL should be extended with parameters such as database authorisation (OUCU) and items
of data.
HTTP
operation
Action Semantics (e.g. SQL)
GET Read the record(s) matching the parameters:
OUCU, TYPE
SELECT address, start, end, type FROM taxi_orders
WHERE oucu=’<OUCU>’ AND type=<TYPE>
POST Create a new record with parameters OUCU,
ADDRESS, START, END, TYPE
INSERT INTO taxi_orders VALUES (<OUCU>,
<ADDRESS>, <START>, <END>, <TYPE>)
PUT Update a record, e.g. modify the ADDRESS for
a given user identified by OUCU
UPDATE taxi_orders SET address=<ADDRESS> WHERE
oucu=<OUCU>
DELETE Delete an existing record matching with ID DELETE FROM taxi_orders WHERE id=<ID>
API queries Base URL
taxi_order http://137.108.92.9/openstack/taxi/orders
taxi_matches http://137.108.92.9/openstack/taxi/matches
4/2/2020 TMA 03: View as single page
https://learn2.open.ac.uk/mod/oucontent/view.php?id=1600344&printable=1 13/17
Each operation can be performed on any table via the API, but not all operations make good sense on all tables;
attempting an operation that is inappropriate will result in an error being returned. Some operations require that you send
some data to the API. So, for example, to delete a record would require passing in a unique ID for the record so that the
required record can be identified and deleted. All records in the database tables have a unique identifying ID item in a
column called ‘id’.
Question 2: API error messages
There are three types of error message:
1. If the API call uses a URL where the URL path does not begin with openstack/taxi,
e.g. http://137.108.92.9/incorrect/taxi/orders then the API will not return any JSON structure but will
return an HTTP header with a 404 response. Note that applications are expected to generate valid URLs; therefore
this error should not occur once you have a working application and so the application itself does not need to handle
this type of error.
2. If the request type is not a valid HTTP verb (GET, PUT, POST or DELETE) then the API will not return any JSON but
will return an HTTP header with a 405 response. As with the previous error message type, the application does not
need to handle this type of error.
3. If the API call is invalid in some way, e.g. an incorrect table name, or the request does not contain the necessary
parameters for the table operation in question, then the API will return a JSON structure that contains an error
message. Various error messages and codes may be produced, but the JSON structures have a common format:
In this structure the string “Some string message” will vary according to the actual error encountered. The error
message can be a string such as
where MESSAGE is the detailed reason from MySQL as to why the GET failed, or
where MESSAGE is the detailed reason from MySQL as to why the INSERT, UPDATE or DELETE failed. The following are
examples of error messages that you may see.
If a GET is performed but no record is returned, then there is a different status in the error message:
“status” : “error”,
“message” : “Some string message”
“
500 – GET error MESSAGE”
” 500 – Execute error MESSAGE”
” 500- Invalid table name for this action.”
” 401 – invalid username”
” 400 – ID field missing”
” 404 – No matching records”
” 500 – foreign key error – oucu not found in taxi_orders table”
” 500 – missing required field for operation”
“status” : “fail”,
“reason”: “404 – No matching records”
4/2/2020 TMA 03: View as single page
https://learn2.open.ac.uk/mod/oucontent/view.php?id=1600344&printable=1 14/17
In general the status can be:
“success”, when there has not been any error.
“fail”, when the request is valid but doesn’t match any record or, in the case of adding a taxi_order, with an order
ID that does not exist. Such errors do not indicate a problem with the calling client program: it is just that the
operation failed because its meaning is incorrect.
“error”, when the request itself is incorrect. For example: if it is missing a critical argument, the argument’s value is
not legal or if the login credentials are incorrect. This sort of error indicates that the calling client has constructed the
request incorrectly in some way.
You should write your code such that you test the value of status and act accordingly. If the value
of status is fail or error, then an application should use the JavaScript alert function to provide an appropriate
message to inform the user or developer of the nature of the error.
Question 2: Explanation of provided code
Here is some code you are given which registers a new user with the service (FR1.1).
Line 17 uses the jQuery method $.post to create a POST request to the service endpoint ‘http://137.108.92.9/openstack/
taxi/users’, which takes one argument OUCU, and returns an argument data for the callback function onSuccess on line 4.
Upon receipt of the data, which is a string value in JSON format, the jQuery method $.parseJSON() is used to parse the
string into a native JavaScript object obj. The structure of the object depends on the returned value. You can tell whether
the response is a success or failure by looking up the attribute obj.status. Line 6 demonstrates how to check if the call
was successful and handle errors as previously outlined.
To illustrate the use of GET and DELETE methods, the code below shows an implementation of FR1.4.
01 function register(oucu)
02 // 2(a) FR1.1
03 // This is implemented for you and no further work is needed on it.
04 var onSuccess = function(data)
05 var obj = $.parseJSON(data);
06 if (obj.status == “success”)
07 alert(“User ” + oucu + ” has been successfully registered.”);
08 else
09 alert(“User ” + oucu + ” is already registered.”);
10
11
12
13 // Post the user ID using the “users” API
14 var uri = “http://137.108.92.9/openstack/taxi/users”;
15 var params = OUCU: oucu ;
16 if (oucu != “”)
17 $.post(uri,params,onSuccess);
18 ;
4/2/2020 TMA 03: View as single page
https://learn2.open.ac.uk/mod/oucontent/view.php?id=1600344&printable=1 15/17
01 function cancel(oucu)
02 // 2(a) FR1.4
03 // This is implemented for you and no further work is needed on it.
04
05 var removeSuccess = function(result)
06 //alert(“Deleted: ” + result);
07
08
09 var listSuccess = function(data)
10 var obj = $.parseJSON(data);
11 if (obj.status == “success”)
12 // for each order found
13 $.each(obj.data, function(index, value)
14 //Use the uri below for the browser
15 var uri = “https://cors-anywhere.herokuapp.com/http://137.108.92.9/openstack/taxi/orde
16
17 //The following may work on a phone
18 //var uri = “http://137.108.92.9/openstack/taxi/orders/” + value.id + “?OUCU=” + oucu;
19
20 // delete the record using an ajax call
21 $.ajax(url: uri, type: “DELETE”,data: ,success: removeSuccess);
22 );
23 alert(“Deleted ” + obj.data.length + ” records”);
24
25 else
26 alert(obj.status + ” ” + obj.data[0].reason);
27
28
29
30 // fetch all the orders (requests and volunteers) for this OUCU
31 var uri = “http://137.108.92.9/openstack/taxi/orders?OUCU=”+ oucu;
32 $.get(uri,listSuccess);
33 ;
4/2/2020 TMA 03: View as single page
https://learn2.open.ac.uk/mod/oucontent/view.php?id=1600344&printable=1 16/17
Line 1 specifies the function for cancelling orders.
Line 5 defines a call back function for when a function is deleted. The alert is commented out but you could uncomment to
help with debugging.
Line 9 defines a call back function for when the current orders are listed. Line 10 parses the HTTP response data that is
provided in JSON format. If this indicates a success (line 11), each item in the provided list (line 13) is deleted (line 21). If
the delete is successful line 5 will be called. Line 15 uses an address to avoid a CORS error occurring. Line 23 tells the
user how many records were deleted. If no records were found, line 26 reports this.
Line 32 is an ajax call to obtain the list of orders from the webservice. When a result is received the code at line 9 is called.
The data field of the object obj.data will be an array, and each element of the array represents an order record. To
delete the order, we use a loop $.each to issue a delete operation with the DELETE request by calling the $.ajax jQuery
method, which has a slightly different syntax from the predefined $.post and $.get methods, in that ‘DELETE’ is passed
in as an argument type, and the URL of this request needs to be parameterised by the order’s ID field (see Line 9).
The implementation of FR3 largely reuses the code you are familiar with from Activity 5 of Block 3 Part 5. Here the function
beginUpdatingMap() at Lines 4 calls updateMatchingStatus() which will implement FR2.1. In this instance the timer
is not shown to the end user – instead we use it to fetch matches from the API. The function stopUpdatingMap will halt
the timer, so no further updates are made.
01 var timerId = null;
02
03 //Start updating the map with matches to the request or volunteer
04 taxiShareObject.beginUpdatingMap = function()
05 // 2(a) FR3
06 // This is implemented for you and no further work is needed on it.
07
08 if (timerId) clearInterval(timerId);
09 // every 10 seconds update the map with the current matches.
10 timerId = setInterval(updateMatchingStatus, 10000);
11 // update the map now too
12 updateMatchingStatus();
13
14
15 //Stop updating the map with matches
16 taxiShareObject.stopUpdatingMap = function()
17 // 2(a) FR3
18 // This is implemented for you and no further work is needed on it.
19 clearInterval(timerId);
20
If you are unable to make progress with Question 2
4/2/2020 TMA 03: View as single page
https://learn2.open.ac.uk/mod/oucontent/view.php?id=1600344&printable=1 17/17
TMA 03 Copyright © 2020 The Open University
If you encounter some technical or unidentified barrier to completing Question 2 it is possible to provide a submission
which explains the problems and which gains a good grade.
Question 2 asks for three functional requirements as a complete implementation to get all the marks. If you don’t get the
app working you may still gain very good marks if you have shown your understanding according to the following outline:
1. Submitted some code or the template with some additional code which appears to be reasonable as a basic attempt
at coding some part, perhaps just one of the ‘FR n’ sections of code (see code earlier).
2. Written some explanation or description of your problem(s) which can be considered as a reasonable barrier to
completing or progressing work. This may be very short – viewing an error message or a behaviour, perhaps there
were few clues as to the problem.
3. Written some outline of how you would have continued to develop the app if what you have produced had worked. If
you have attempted all FRs (under ‘1’) above this section may amount to ‘I just needed to get the code I have
produced to work’.
4. Other items such as how you attempted to work around or fix problems. This might be actions you took yourself or it
might consist of browsing forums, posting to a forum or consulting your tutor.
When, for example there are few clues to the problem (for ‘2’) it should be the case that there is some content for 4. You
may have encountered more than one problem and shown an ability to deal with some. You should provide screen
captures of the problems encountered to support your case.
The post TMA 03 Printable page generated appeared first on My Assignment Online.
