Server API HTTPS and JSON

Server API is based on HTTPS and JSON. Clients send messages to the server following the API, and handle 
responses from the server. 
For overview and further details on the requirements of the system, see the course project work 
requirements elsewhere. This document only documents the API that must be supported by server and 
client implementations. 
Please note that automatic tests will be conducted to verify the functionality. Therefore, both the server 
and the client MUST follow this API. Failing to do so fails the tests. If specific input/output is given in the 
requirements, it must be the same in your coursework.
Assignment specifications
Minimum requirements
This section provides the minimum requirements for the coursework, ALL requirements must be completed
REQ1 All text in HTTP body MUST be UTF-8. 
REQ2 All content in the HTTP requests and responses MUST be JSON except for the error messages from 
server which may be text. 
REQ3 All dates and times in JSON content MUST follow the ISO 8601 date format in UTC time zone with 
milliseconds, e.g. 2020-12-21T07:57:47.131Z. 
REQ4 All times must follow the following pattern: “2020-12-21T07:57:47.123Z”
REQ5 HTTP Headers MUST contain the content size in bytes and content type using standard HTTP 
headers.
REQ6 HTTP header Content-Type MUST be “application/json”.
REQ7 Database MUST be used to store all user sent data
1.1. Feature 1: User can send inform others about a sightseeing location
URL: https://server.url/info
Request type: POST
Response code for successfully operation: 200
Response code failed operation: 400-499
Header information that must be included in minimum: 
- Content-Length: size of the content
- Content-Type: application/json
Authorization: only registered users can perform this operation
Data format for posting a sightseeing location:
{
“locationName” : “Oulun Tuomiokirkko”,
“locationDescription”: “The church of oulu”,
“locationCity”: “Oulu”,
“locationCountry” : “Finland”,
“locationStreetAddress”: “Kirkkokatu 3 A”,
“originalPoster” : ”Pekka”,
“originalPostingTime” : “2020-12-21T07:57:47.123Z”
}
Where:
- locationName is the name of the location and can be chosen by the user
- locationDecription where user can provide a short freely written description about the location
- locationCity is the name of the city where the sightseeing location is
- locationStreetAddress is the local address for the sightseeing location
- originalPoster is the name of the person who sent the location information (user’s chosen 
nickname taken from the user’s profile, not to be mixed with login username)
- originalPostingTime time when the user sent the location information, represented in UTC
NOTE: The server doesn’t care whether same location has been sent multiple times so you must make sure 
every location information is unique even it has the same information
1.2. Feature 2: Get sightseeing locations posted by users
URL: https://server.url/info
Request type: GET
Response code for successfully operation: 200
Response code failed operation: 400-499
Header information that must be included in minimum: 
- Content-Length: size of the content
- Content-Type: application/json
Authorization: only registered users can perform this operation
Data format for sending locations back to client:
[
{
“locationName” : “Oulun Tuomiokirkko”,
“locationDescription”: “The church of oulu”,
“locationCity”: “Oulu”,
“locationCountry” : “Finland”,
“locationStreetAddress”: “Kirkkokatu 3 A”,
“originalPoster” : ”Pekka”,
“originalPostingTime” : “2020-12-21T07:57:47.123Z”
},
{
“locationName” : “Nallikari Beach”,
“locationDescription”: “Local beach at Nallikari”,
“locationCity”: “Oulu”,
“locationCountry” : “Finland”,
“locationStreetAddress”: “Leiritie 10”,
“originalPoster” : ”Anna”,
“originalPostingTime” : “2023-12-21T07:57:47.123Z”
}
]
NOTE: Server MAY also response with 204 and empty response body if there are no coordinates to deliver
to the client.
1.3. Feature 3: Register and authenticate 
URL: https://server.url/registration
Request type: POST
Response code for successfully operation: 200
Response code failed operation: 400-499
Header information that must be included in minimum: 
- Content-Length: size of the content
- Content-Type: application/json
Authorization: N/A (user can register an account without previous credentials)
Data format for registering user:
{
“userName” : “username”,
“password” : “password”,
“email” : “user.email@for-contacting.com”,
 “userNickname” : “Pekka”
}
Description:
Server MUST NOT accept other than registration requests from unauthorized clients. Client MUST send 
passwords using HTTPS. Passwords MUST not be sent over insecure HTTP connections. Server MUST not 
store the plain password, but only store a hash of it. A good hash function MUST be used to make sure 
hashed passwords are secured and as unique as possible to avoid collisions.
For other than registration requests, users MUST be authenticated using Basic HTTP authentication (see 
References). Authentication MUST be done over HTTPS using the Authorization header, where 
username:password string MUST be UTF-8. 
1.4. Feature 4: User can attach coordinate information to the sightseeing 
data
URL: https://server.url/info
Request type: POST
Response code for successfully operation: 200
Response code failed operation: 400-499
Header information that must be included in minimum: 
- Content-Length: size of the content
- Content-Type: application/json
Authorization: only registered users can perform this operation
Data format for posting a sightseeing location:
{
“locationName” : “Oulun Tuomiokirkko”,
“locationDescription”: “The church of oulu”,
“locationCity”: “Oulu”,
“locationCountry” : “Finland”,
“locationStreetAddress”: “Kirkkokatu 3 A”,
“originalPoster” : ”Pekka”,
“originalPostingTime” : “2020-12-21T07:57:47.123Z”
, “latitude”: “65.0580507136066”,
“longitude”: “25.469414591526057”
}
Where:
- latitude and longitude represent a geolocation based on java html geolocation api (such as used in 
google maps for example).
NOTE: Coordiates are not mandatory, if no coordinates exist for a sightseeing location, no coordinate 
information is provided in a message when requested from the server.
Advanced API
Any of the following features successfully implemented (passes unit tests and matches requirements) 
increases the assignment grade by 1. For example, if two additional features are implemented successfully, 
the grade of the assignment 3. If all exercises are also successfully completed, the final course grade is 4.
Feature 5: Attach weather when sightseeing information is requested
URL: https://server.url/info
Request type: POST
Response code for successfully operation: 200
Response code failed operation: 400-499
Header information that must be included in minimum: 
- Content-Length: size of the content
- Content-Type: application/json
Authorization: only registered users can perform this operation
Data format for posting a sightseeing location:
{
“locationName” : “Oulun Tuomiokirkko”,
“locationDescription”: “The church of oulu”,
“locationCity”: “Oulu”,
“locationCountry” : “Finland”,
“locationStreetAddress”: “Kirkkokatu 3 A”,
“originalPoster” : ”Pekka”,
“originalPostingTime” : “2020-12-21T07:57:47.123Z”
, “latitude”: “65.0580507136066”,
“longitude”: “25.469414591526057”,
“weather”:””
}
Where:
- weather is a integer, double or “1C” representation of weather given from the weather service
Other information:
- User can opt to attach weather information 
- Weather information is based coordinate location
- Weather information is obtained from custom build service that provides basic weather 
information based on coordinates
- The messages with weather information must contain temperature information from the location 
specified in the request
- The weather service will be provided separately, the server must send the coordinates to the 
weather service that will provide the weather information to be added to the coordinates
Feature 6: User can create sightseeing paths with custom tour message
URL: https://server.url/paths
Request type: POST
Response code for successfully operation: 200
Response code failed operation: 400-499
Header information that must be included in minimum: 
- Content-Length: size of the content
- Content-Type: application/json
Authorization: only registered users can perform this operation
Data format for posting a tour:
{
“tour_name” : “Quick city center run”,
“tourDescription”: “15 minute tour in Oulu”,
“locations” : 
[
{
“locationID”:”1”
}
]
}
Where:
- tour_name is a string name for the tour
- tourDescription is a string description of the tour
- locations is a JSONArray of locations in the tour
- locationID is an unique integer representing a specific location
URL: https://server.url/paths
Request type: GET
Response code for successfully operation: 200
Response code failed operation: 400-499
Header information that must be included in minimum: 
- Content-Length: size of the content
- Content-Type: application/json
Authorization: only registered users can perform this operation
Data format for returning a tour:
[
{
“tour_name” : “Quick city center run”,
“tourDescription”: “15 minute tour in Oulu”,
“locations” : 
[
{
“locationID”:”1”
“locationName” : “Oulun Tuomiokirkko”,
“locationDescription”: “The church of oulu”,
“locationCity”: “Oulu”,
“locationCountry” : “Finland”,
“locationStreetAddress”: “Kirkkokatu 3 A”,
“originalPoster” : ”Pekka”,
“originalPostingTime” : “2020-12-21T07:57:47.123Z”
}
]
}
]
Other information
- User can select certain locations (each location has an unique id) as a sightseeing path
- Path is not ordered but rather a “collection” of locations 
- locations contain a jsonarray that has a list of locations based on their id (create id for your 
message), there is no limit for locations other than how many locations a test adds
Feature 7: Sightseeing information can be updated
URL: https://server.url/info
Request type: POST
Response code for successfully operation: 200
Response code failed operation: 400-499
Header information that must be included in minimum: 
- Content-Length: size of the content
- Content-Type: application/json
Authorization: only registered users can perform this operation
Data format for posting an update to an existing message:
{
 “locationID”:”1”
“locationName” : “Oulun Tuomiokirkko”,
“locationDescription”: “The church of oulu”,
“locationCity”: “Oulu”,
“locationCountry” : “Finland”,
“locationStreetAddress”: “Kirkkokatu 3 A”,
“originalPoster” : ”Pekka”,
“originalPostingTime” : “2020-12-21T07:57:47.123Z”
}
Where:
- locationID is an unique integer representing a specific location (it needs to be given by the server 
when the original location is posted)
Example server response for GET
[
{
 “locationID”:”1”
“locationName” : “Oulun Tuomiokirkko”,
“locationDescription”: “The church of oulu”,
“locationCity”: “Oulu”,
“locationCountry” : “Finland”,
“locationStreetAddress”: “Kirkkokatu 3 A”,
“originalPoster” : ”Pekka”,
“originalPostingTime” : “2020-12-21T07:57:47.123Z”
“updatereason”: “just updating stuff”,
“modified”: 2024-1-21T07:57:47.123Z”
}
]
Where:
- originalPostingTime is the original timestamp of the location when it was posted first time
- updatereason is a string where user can state a reason for the update
- modified is a timestamp when the edit was made
Other information:
- User can send updates to the sightseeing locations user has sent
o The modified message must show a timestamp of the latest edit
- In order to identify any location, supply an ID (integer) with the message to provide the update to a 
right message
- Whether user is allowed to update the message, the server needs to check if the user (not 
nickname) has posted the danger message previously. Remember, the nickname is just nickname 
user chooses for particular message, the real identificatory is the registered user
- User can give a reason for the update or leave the field empty (it still must be included in the 
message when being updated and when retrieving updated messages from the server)
Feature 8: Server tracks how many times sightseeing location is “visited”
URL: https://server.url/info
Request type: POST
Response code for successfully operation: 200
Response code failed operation: 400-499
Header information that must be included in minimum: 
- Content-Length: size of the content
- Content-Type: application/json
Authorization: only registered users can perform this operation
Data format for posting a visit to a site:
{
 “locationID”:”1”
“locationVisitor” : “Pekka”
}
where 
- locationID is unique integer for the location given by the server
- locationVisitor is a string representing a user
Example response to get request in info context:
[
{
 “locationID”:”1”
“locationName” : “Oulun Tuomiokirkko”,
“locationDescription”: “The church of oulu”,
“locationCity”: “Oulu”,
“locationCountry” : “Finland”,
“locationStreetAddress”: “Kirkkokatu 3 A”,
“originalPoster” : ”Pekka”,
“originalPostingTime” : “2020-12-21T07:57:47.123Z”
“timesVisited”:”1”
}
]
where
- timesVisited is an integer representing how many times the place has been visited
URL: https://server.url/topfive
Request type: GET
Response code for successfully operation: 200
Response code failed operation: 400-499
Header information that must be included in minimum: 
- Content-Length: size of the content
- Content-Type: application/json
Authorization: only registered users can perform this operation
Example response to get request in topfive context:
[
{
 “locationID”:”12”
“locationName” : “Snägäri”,
“timesVisited”:”899”
},
{
 “locationID”:”7”
“locationName” : “Lentokenttä”,
“timesVisited”:”100”
},
{
 “locationID”:”2”
“locationName” : “Nallikari”,
“timesVisited”:”40”
},
{
 “locationID”:”10”
“locationName” : “Kaupungintalo”,
“timesVisited”:”5”
},
{
 “locationID”:”1”
“locationName” : “Oulun Tuomiokirkko”,
“timesVisited”:”1”
}
]
Other information:
- Server adds a counter to each sightseeing location to indicate how many times it has been 
requested from the server
o Note that this only simulates the “visit counter”
- User can request “top 5 destinations” from the server and the server needs to send the 5 most 
viewed locations to user
Extra Feature 9: AI location identification
URL: https://server.url/info
Request type: POST
Response code for successfully operation: 200
Response code failed operation: 400-499
Header information that must be included in minimum: 
- Content-Length: size of the content
- Content-Type: application/json
Authorization: only registered users can perform this operation
Data format for posting a visit to a site:
{
“locationName” : “Oulun Tuomiokirkko”,
“locationDescription”: “ai_auto_fill”,
“locationCity”: “Oulu”,
“locationCountry” : “Finland”,
“locationStreetAddress”: “Kirkkokatu 3 A”,
“originalPoster” : ”Pekka”,
“originalPostingTime” : “2020-12-21T07:57:47.123Z”
, “latitude”: “65.0580507136066”,
“longitude”: “25.469414591526057”
}
Other information:
- the field with ai_auto_fill needs to be updated with AI response based on other information given 
in the message
- the response must be at least 50 characters
- the test only checks if the description is provided in the returning message and if it is at least 50 
characters long
- the description is manually checked in order to see whether the text is corresponding to the 
location data and not just some random characters
- The AI component is chat4all open source AI that you can download and use in your own computer. 
For instructions, see lecture video about AI and example codes are available in the extra section in 
moodle.
Additional Quality Improvements
If the software quality is high enough, the final grade of the assignment can be increased by 1. Note that 
these are evaluated by the teacher and there are no guidelines what is required in minimum. Here are 
examples of the quality aspects we look for:
• Properly commented code/interfaces
• Usage of unit tests
• Old messages are archieved after certain amount of time (for example after 2 months the messages 
are removed from the actual database to for example a text file or other database to prevent the 
database becoming too large affecting the speed of it)
• System backup
• System recovery
• Clean code