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
Coursework minimum requirements
These requirements MUST BE COMPLETED or the work is rejected.
1.1. Feature 1: Posting a message (50 points)
Posting a message happens using HTTP POST to URL https://server.url/coordinates
The HTTP request MUST include Content-Length, Content-Type and Authorization headers with proper
values.
HTTP body MUST have the following elements in the content:
{
“username” : “nickname”,
“longitude”: “25.469414591526057”,
“latitude”: “65.0580507136066”,
“sent” : “2020-12-21T07:57:47.123Z”
}
Where message is the chat message sent by the user, and sent is the timestamp when the user decided to
send the message in the user local time, represented in UTC.
Server design MAY put limits on the size of the message. Server may either ignore the extra data or provide
an error code for the client in this case.
1.2. Feature 2: Get coordinates posted by user
Fetching coordinates user has stored from the server happens using HTTP GET and URL
https://server.url/coordinates/
When successful, server MUST response with response code 200 and the following response headers:
1. Content-Length – size of the content in bytes in response
2. Content-Type – should be application/json for coordinates
Server MAY also response with 204 and empty response body if there are no coordinates to deliver to the
client.
Server response body contains the coordinates in a JSON array:
[
{
“username” : “nickname”,
“longitude”: “25.469414591526057”,
“latitude”: “65.0580507136066”,
“sent” : “2020-12-21T07:57:47.123Z”
},
{
“username” : “nickname”,
“longitude”: “25.469414591526057”,
“latitude”: “65.0580507136066”,
“sent” : “2020-12-21T07:57:47.123Z”
}
]
1.3. Feature 3: Store user information in to a database
All data in the server must be stored in to a database, including:
- User information
- Coordinates (longitude and latitude information)
- Timestamp
- ALL other data that is added by additional features (if they are completed)
Feature 1.4: User can ask coordinates with different search parameters
- User can ask coordinates that have been posted by a specific user
- User can ask coordinates that have been posted between certain time window
Example POST with username
{
“query”:”user”,
“nickname”:”Seppo”
}
{
“query”:”time”,
“timestart”: “2020-12-21T07:57:47.123Z”,
“timeend”: “2022-12-21T07:57:47.123Z”
}
Additional features
The following features contribute additional points to the final work, they are not required BUT adding
these features to your final work will give you additional points to your final score.
Feature: Register and authenticate users (30 points)
Registering a user happens using HTTP POST to URL https://server.url/registration.
HTTP body for the registration message MUST have the following content:
{
“username” : “username”,
“password” : “password”,
“email” : “user.email@for-contacting.com”
}
After registration, clients MUST authenticate with the username and the password for executing requests
to the server. 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 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 and MUST be Base64 encoded.
Clients SHOULD cache the user credentials after initial client side authorization for a period of time. Clients
may either:
• cache the credentials for a single client session, keeping username and password in memory, or
• save the credentials locally to a file, so user does not need to authenticate unless explicitly logging
out of the chat server.
If client saves the credentials on the client side file, this MUST be done securely
Feature: Coordinates can have descriptions (10 points)
Users can attach descriptions to the coordinates, limited to 1024 characters. The field is not mandatory but
in case user sends an empty description, the server can replace the description with ‘nodata’ -character
string if wanted. Example message:
{
“username” : “nickname”,
“longitude”: “25.469414591526057”,
“latitude”: “65.0580507136066”,
“sent” : “2020-12-21T07:57:47.123Z”,
“description”: “I think this is somewhere in university”
}
Feature: Comment coordinates (10 points)
- User can comment coordinates posted to the server
- Registered user can comment any coordinates
- Coordinate in server must store all comments given to the certain coordinate
- When coordinate is requested, all stored comments are delivered with the coordinate
- In order to identify the message, supply an ID (integer) with the message to provide the comment
to a right coordinates
- Use new context for commenting coordinates ‘/comment’ that listens only comment POST
messages
Example POST comment:
{
“id” : “125”, //not necessary but you can keep it in the comment
“comment”: “I think this is an unviersity”,
“sent” : “2020-12-21T07:57:47.123Z”
}
Example GET request from coordinates:
[
{
“id”: “125”,
“username” : “nickname”,
“longitude”: “25.469414591526057”,
“latitude”: “65.0580507136066”,
“sent” : “2020-12-21T07:57:47.123Z”
“description”: “I think this is somewhere in university”
“comments”: [
{
“id”:”125”
“comment”: “I think is an university”,
“sent” : “2020-12-21T07:57:47.123Z”
}
]
}
]
Additional Quality Improvements and general requirements (max 30
points)
If the work includes any quality improvements or general requirements, these additional improvements can
increase your final score up to maximum of 30 points. Note that these are evaluated by the teacher and
there are no specific guidelines but as an example, the following quality aspects are being evaluated:
• 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
• …
General requirements
This section provides general requirements for the coursework, fulfilling requirement(s) contributes
additional points in final assignment score.
REQ-001 All text in HTTP body MUST be UTF-8.
REQ-002 All content in the HTTP requests and responses MUST be JSON except for the error messages
from server which may be text.
REQ-003 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.
REQ-004 All datetimes in HTTP headers MUST follow the "HTTP-date" format as defined by RFC 7231
with milliseconds, eg. Tue, 15 Nov 1994 12:45:26.231 GMT
REQ-005 All binary data MUST be Base64 encoded. (this is ONLY if your assignment submission INCLUDES
binaries! In other words, if your repository has binary files)
REQ-006 HTTP Headers MUST contain the content size in bytes and content type using standard HTTP
headers.
REQ-007 All HTTP requests except for registration MUST contain authentication credentials if user
registration is supported in the server.
REQ-008 HTTP header Content-Type MUST be “application/json”.
REQ-010 Database MUST be used to store all user sent data