CAB230 Web Computing Assignment Getting Started with the API
Version of 11 April 2019, 11:00PM.
Note that the guide and the code have been substantially updated to reflect new
filtering options and the switch to https. The final URL is: https://cab230.hackhouse.sh/.
This document presents a short guide to help you get started with the API you will be using over the course of the assignment. Initially, you will work with this site purely as a data source. In what follows we will work through the process of hitting this API using fetch based JavaScript calls as we did in the lecture and the prac for week 5.
As discussed in the lectures, we will be working with a dataset based on the following crime statistics made available by the state government:
https://data.qld.gov.au/dataset/lga_reported_offender_numbers/resource/32d7bc11- 55ed-4c52-86ff-e9d780cfe9ce
As you can see if you select the visualisation tab, there are a massive number of columns listed, each reflecting an offence or range of offences covered by the criminal justice system.

The site is quite sophisticated, and allows the user to sort and filter based on a range of data source selections and criteria. There is also the option to graph particular fields or to show the incidence of offences by geographical region on a map. If you want a grade of 6 or 7 standard mark for the client side of this assignment, then you will have to do the same. Start using this site to explore your ideas.
As you now know, Tylor took this CSV file and wrangled the data into a form which is more suitable for a small, well-defined API. There are a range of endpoints available to you, and these are listed briefly, and without a lot of detail, in the bullet points below. The difference from the earlier version is that we now have available a range of other parameters to use as filters in the offences search.
It is easier now to group the endpoints into three categories:
Getting Started:
/register (POST) Register using email and password
/login (POST) Logging into your account using the details provided.
This allows access to authenticated routes via a JSON Web Token.
Information (Open Endpoints):
/offences (GET) returns an array of offences recorded. (Open endpoint).
/areas (GET) returns array of Local Government Areas. (Open endpoint).
/ages (GET) returns an array of age categories. (Open endpoint).
/genders (GET) returns an array of gender categories. (Open endpoint).
/years (GET) returns an array of years recorded. (Open endpoint).
All of the information endpoints provide a list of legal values for the parameters of the search endpoint usually just drop the s at the end of the word.
Search (Requires Authentication):
/search?offence=xxx (GET) The primary search route. Note that query params need to be url encoded. (Requires authentication).
/search?offence=xxx&param1=xxxx&param2=xxxx (GET) The primary search route, but this time with optional filter parameters, which again must be url encoded. (Requires authentication).
Paramsmustbeoneof:area,age,gender,year,month
Informationroutesareavailableforallparamsexceptmonth,whichruns
from 1,2,,12
Examples are provided below for offences and offence. Here we begin with the example of Armed Robbery, and this is used as the basis for subsequent filtering.

Information Endpoint: /offences
Search Parameter: offence (required)
Example values: Armed Robbery,Attempted Murder,Bomb Possess and/or use of Example use: https://cab230.hackhouse.sh/search?offence=Armed%20Robbery
Note that this is the standard search we have provided an offence (which is required) and we will see an array of records which cover all of the armed robbery offences in the database. We end up returning this (heavily edited) JSON:
{query:{offence:Armed Robbery},
result:[
{LGA:Aurukun Shire Council,total:124}, {LGA:Balonne Shire Council,total:13}, {LGA:Banana Shire Council,total:5}, {LGA:Barcaldine Regional Council,total:0}, {LGA:Barcoo Shire Council,total:0}, {LGA:Blackall Tambo Regional Council,total:0}, {LGA:Boulia Shire Council,total:0}, {LGA:Brisbane City Council,total:4049},

{LGA:Winton Shire Council,total:0}, {LGA:Woorabinda Shire Council,total:10}, {LGA:Wujal Wujal Shire Council,total:0},
] {LGA:Yarrabah Shire Council,total:6}
}
The role of the other (filter) parameters is then to limit these results based on some criteria. For example, an armed robbery query with filtering to the Moreton Bay Regional Council Area yields the following:
{query:{offence:Armed Robbery,area:Moreton Bay Regional Council},result:[{LGA:Moreton Bay Regional Council,total:958}]}
In the code examples, I have considered a number of filter parameters: area, age and year. Note that the example for year shows the use of multiple values, with the query returning results for 2006, 2007 and 2008. Multiple values are comma separated, and the comma acts as a logical OR. The examples use only a single filter, but the API allows chaining of filters as in the examples on the root page at https://cab230.hackhouse.sh/.

These endpoints will be fixed for the remainder of the assignment. We will improve the documentation at the root and share this with you when we release the server side specification.
Some Code
The goal of this document is not to provide you with a comprehensive API reference, but to get you started in using the API to the point that you can register, and login and do some queries. The material relies heavily on the week 5 lecture and the week 5 prac. We are here to hit a public API with a series of POST and GET calls. We will be using the modern fetch() approach introduced in the lecture, and there will not be a single XMLHttpRequest in sight.
Our approach will be to build on the earlier prac work, defining buttons for each of the tasks we want to manage. The account registration should be executed only once for each email address. Please just use your QUT email and register once and once only.
In what follows we are going to use the innerHTML on the page only to show the good bits. For the error messages, you will need to open up the console in the page as you did in the debugging exercises in the prac.
The code is available in the starter-files.zip archive as usual. These are very basic calls and are intended solely to get you started. In particular, I am not doing any of the form processing here for basic HTML you will find this at W3Schools. For React, please see the React Forms guide available near to this file on BB. The code provided here will be a good basis for the first stages of the assignment.
The HTML page is very simple. We begin with a cute heading at the top, we include two sets of buttons, and we then follow with a single result div which we call app. Each button

affects that div. We do not maintain the result of any previous calls. We will, however, need to keep track of a token, and that is something we will consider in a moment. The basic html looks like this:

Getting Started with Crime (Updated)

Armed Robbery Offences Filtered

Query Responses