COMP9321 Assignment - REST API MyCalendar
REST API MyCalendar
In this assignment, you are asked to develop a time-management and scheduling calendar service (Google Calendar) for Australians using Flask-Restx. For this assignment, you can use the following Free Rest APIs or datasets
• Get public holidays for a specific country and year Australia - Holidays • Weather Forecast API: Weather API . To get a better understanding of what this API returns take a look at this chart: Sample Chart and read the API specifications: Weather API Wiki • Australia's Cities Dataset • Australia Suburb Dataset
It is part of the assignment that you should explore the datasets and APIs to see how you can use them to fulfil the assignment requirements.
Disclaimer: We are using external APIs and Datasets. We want the students to interact with real-life web services to add to the learning experience and hence we are not responsible nor liable for the wording or inclusion/exclusion of entities and descriptions within the API. This is a "building your REST API" exercise and should be treated as such.
Assignment Specification
Question-1: Add a new event (2 mark)
This operation is to add a new event to your calendar. Please check the example below to see what attributes an event should have Example:
POST /events
"name": "my birthday party", "date": "01-01-2000"
"20:0:Or"'
'loation": {
"street": "215B Night
uurb": "Kensington
Ave",1
"post-code": "2033"
"description" : "some notes on the event"
}After creating the event, the service should return a response containing at least the following information:
• id : a unique integer identifier automatically generated by your service (can be either incremental id, or any or any unique identifier) • last-update the time the collection is stored in the database • _links : the URL with which the same event can be retrieved (as shown in below example)
An example response 'This is not what you store in DB, it is the call's response] : 201 Created
{
'id" : 123,
"last-update": "2023-04-08 12:34:40",
"links": { "self": {
"href": "/events/123"
}Note: Your API should not allow adding a new event, or modifying an event if it has overlapping time with other events_ For instance, one event can finish at 16:00 on the same day that another starts at 16:00. it cannot start at 15A5.
Marking Criteria: • (1 Mark) Ability to add an event and check for overlappings • (1 Mark) API documentation, Error Handling, Sticking to RESTful Principle (e_g., proper HTTP status codes, response content type)
Question 2 - Retrieve an event by its id (4 marks)
This operation retrieves an event by its ID (the 10 that is generated by your application) . The response of this operation will show event details. Please see the provided response example below to see what attributes should be included in the response. 'links' gives the links for previous, next. and current resources if they exist . The "_links" in the response should contain the previous and next events after the retrieved event. The previous and next events are based on the date and time of the events, not on when the events were last updated or their ids.
The response should have metadata information including if it is a public holiday or weekend, as well as the weather forecast and daylight details if it starts in the next 7 days. Take a look at the sample response above to see what you need to extract from the given APIs and the dataset to achieve this. You can choose any format for the metadata fields as long as they may sense and are precise. For example. the temperature unit can be Fahrenheit or Centigrade, but it should be self-explanatory for the user.
_links and _meta clat are extra information and they are not part of the main resource (events). As such their values are populated at the time of retrieval and they are not stored in your DB.
The interface should look as below:
GET /events/(id}Example Response returns: 200 OK
{
"id": 124,
"last-update": '2023-03-08 12:34:49", "name": "easter party",
"date"; "09-04-2023"
"from": "16;013",
"to': '20:00",
"location":
"street": "215B Night Ave",
'suburb": "Kensington",
"post-code": "2033"
"description" : "some notes on the event',
"_metadata" : {
"sunrise": "02:18:15", "sunset": "16:01:47", "wind-speed": "3 KM", "weather": "cloudy", "humidity": "66%",
"temperature": "20 C", "holiday": "Easter", "weekend": false
},
{
"self": {
"href": "!events/124"
"previous": T
"href": "fevents1250"
"next". {
"href": "'events/165"
}
}
}Marking Criteria: • (1 Mark) Ability to retrieve the given event with required properties • (0.5 Marks) Returns proper links in the response ("_ink') • (1.5 Marks) Returns required metadata links in the response ("_metadata") • (1 Mark) API documentation Error Handling, Sticking to RESTful Principle (e g , proper HTTP status codes, response content type
Question 3- Deleting an event (2 marks)
This operation deletes an existing event from the database. The interface should look like as below:
DELETE /events/{id}Returns: 200 OK
{
"message" :"The event with id 134 was removed from the database!", "id": 134
}Marking Criteria: • (1 Mark) Ability to delete the given event • (1 Mark) API documentation. Error Handling; Sticking to RESTful Principle (e.g., proper HTTP status codes; response content type)
Question 4 - Update an event (2 marks)
This operation partially updates the details of a given event. The interface should look like the example below:
PATCH /events/{id}
{
"from": "16:39",
"to": "20:30"
"description" : 'same notes on the event"
}The above payload is lust an example; it can contain any of the events' attributes. Returns: 200 OK
{
"id' : 123,
"last-update": "2023-04-138 12:34:55",
"links": {
"self": {
"href": "/events/123"
}
}
}Marking Criteria: • (1 Mark) Ability to update the given event • (1 Mark) API documentation, Error Handling; Sticking to RESTful Principle (e.g.; proper HTTP status codes, response content type)
Question 5 - Retrieve the list of available events (5 marks)
This operation retrieves all available events. The interface should be:
GET /events?order=<CSV-FORMATED-VALUE>,&page=1&size=10&filter=<CSV-FORMATED-VALUE>All four parameters are optional with default values being "order=+id", "page=1", and "size =10", filter="id,name". "page" and ''size" are used for pagination; "size' shows the number of events per page. "order" is a comma-separated string value to sort the list based on the given criteria. The string consists of two parts: the first part is a special character '+' or where '+' indicates ordering ascendingly, and '-' indicates ordering descendingly. The second part is an attribute name which is one of {id, name, datetime}. Here are some sample values of 'order : order by "name ascending" and ''id ascending"
+name,+id In this case sorb rig by "name has p riarity over le This is similar tc SOL cider by clause : " name ASC, id ASC order by "datetifne descending"; it is like listing the latest event first.
- datetime "date/me" is the combination of "date" and "from" properties in the events
"filter is also another comma-separated value (combination of: id, name, date, from to: and location), and shows what attribute should be shown for each event accordingly. Take a look at the following example:
GET /events?order=i-icapage=18,size=10.ifilter.id,nameAll four parameters are optional with default values being 'order=+id", "page=1", and "size=10", "fliter=icf,name" Returns- 200 OK
"page"; 1,
"page-size": 10, "events": f
"id" ; 1,
"name" : "my birthday party"
"id" 2,
"name" : 'my dental appointment"
},
"links": {
"self": {
"href": "fevents?order=+id&page=l&size=legfilter=id,name"
},
"next": {
"href": "ievents?order=+idipage=2&size=164filter=id,name"
}Marking Criteria: n (1 Mark) Ability to retrieve the given events • (1 Mark) Implementation of the pagination feature n (1 Mark) Implementation of the Filtering feature n (1 Mark) Implementation of the Sort featured • (1 Mark) API documentation: Error Handling, Sticking to RESTful Principle (e.g.: proper HTTP status codes response content type)
Question 6 - get the statistics of the existing Events (2.5 marks)
This operation accepts a parameter called "format" which can be either "jscri" or "image". Depending on the format your operation should provide the following information: In case when the format is an image, your operation should return an image (can be in any image format) and the image illustrates the requested information in a visualization (apply all your knowledge when creating the visualization such as choosing appropriate visualization type and making sure that it is human-readable, clear, and informative).
• Number of events per day • Total Number of events • Total Number of events in current calendar Week (Today to Sunday) and current calendar Month (1st to the last day of the month)
The interface should look as below when the format is JSON:
GET ievents/statistics?format=jsonReturns: 200 OK
{
"total-, 10,
"total-current-week"; 5,
"total-current-month" 3,
"per-days" : { "10-04-2023", 3, "11-04-2023". 2, "13-04-2023":3, "18-05-2023":2}
}Marking Criteria: • (0.5 Mark) Ability to retrieve the given data in JSON format • (1 Mark) Ability to retrieve the given data in Image format • (1 Mark) API documentation, Error Handling, Sticking to RESTful Principle (e.g., proper HTTP status codes. response content type), proper visualization chart type with proper details to demonstrate the information to its audience.
Question 7 - Australia's weather forecast (2.5 marks)
This operation accepts a parameter called "date" and represents the weather forecast for Australia's main cities on Australia's map • For this assignment, you can use Geopandas The interface should look as below:
GET /weather?date=13-05-2023Returns: An image showing the forecast on the map This is just a sample output from 9 News Channel (not necessarily what you must present):
• (1.5 Mark) Ability to show weather on the map
• (1 Mark) API documentation, Error Handling, Sticking to RESTful Principle (e.g., proper HTTP status codes, response content type)
Notice:
• Your data should be persisted in sqlite database name as "YOU R_ZI D.db" • You can only use the libraries (latest versions) used in the Labs or mentioned in the assignment spec. • Your submission will be marked manually. • You should adhere to the best design guidelines for REST API mentioned in the lecture (e.g., appropriate responses based on JSON format with proper status codes, full API documentation: the generated Swagger should be fully self-explanatory with an operation summary, parameter descriptions, and default values). • You should consider cases such as invalid inputs or any invalid attempts to use the endpoint ( e.g. If the event doesn 't exist in the data source, return error 404) • You API should return appropriate responses (JSON or images)
• Your code must be implemented in flask-restx and automatically generate a swagger doc for testing the endpoints. • Your code must be executable in CSE machines • Your code must not require installing any software (python libraries are fine) • Your code must be written in Python 3.5 or newer versions. • Your operations (API methods) must return appropriate responses in JSON format, and an appropriate HTTP response code! e.g., 500 Internal Server Error is an inappropriate response! • Make sure you are using the right datatypes in the database and in your API methods (e.g., not string for years '2017') • Some of the responses of some operations contain "_links", depending on the response this should include links to "self", "next", and "previous" resources. FAQ: • What is the date-time format? You can use any format (human-readable), but it should be the case for all date/time values, including birthday, last updated
• What libraries can I use? You can use all libraries imported in any labs, plus SQLAlchemy • Can API users update ID, links, and Last-update time? No, these attributes are not editable by the user. An ID should be never changed, links and last-update fields are not part of the attributes of an event. Submission: • The Deadline is Tue the 4th of April 2023 20:00 • There is no template code for this assignment, your submission should stick to the assignment specifications and should be runnable as follow: python3 YOUR_ZID.py georef-australia-state-suburb.csv au.csv You must submit two files, your python script and requirements.txt (standard file containing all modules you require for running your script).
