FastTrack'D - "Social Media" Assessment
This is a project that I worked on in a team in an Agile-simulated environment.
CLICK HERE FOR ALL OF MY COMMITS.
Overview
For this assessment, you are tasked with implementing a RESTful API using Spring Boot, JPA, and Postgresql. Specifically, you will be implementing an API that exposes operations for social media data that resembles the conceptual model of Twitter.
You will implement this API from scratch, working from a series of endpoint specifications (found at the end of this document) to develop a mental model of the data. You will develop a suitable database schema and write Spring services and controllers to handle requests, perform validation and business logic, and to transform data between the API and database models.
Reading these Requirements
RESTful Endpoint Methods and URLs
Each endpoint you are required to implement is documented by the REST method and URL used to access it. For example, an endpoint used to access the list of dogs maintained by a server might be described like:
GET dogs
This tells us that the endpoint requires the GET
HTTP method and is located at the dogs
url, i.e. at http://host:port/dogs
.
URL Variables
Some endpoints have variables in their urls, and these are represented by a variable name surrounded by curly braces. For example, an endpoint that returns a breed of dog by name might be described by the following syntax:
GET breeds/{breedName}
This tells us that the endpoint captures the path segment following breeds/
with the variable breedName
.
Remember that the curly braces themselves are not part of the url, but anything outside of them is.
Trailing Slashes
The endpoint specifications never supply a trailing slash, but they are allowed. It is up to you to decide whether you prefer trailing slashes for API endpoint URLs or not, but whichever you choose, be consistent from endpoint to endpoint.
Types and Object Properties
The syntax used to describe the request and response bodies for each required api endpoint is a variation of javascript's object literal syntax, in order to promote legibility, but the endpoints themselves should use JSON to represent data.
Object literals are used to describe the shape of each data model, and property values are used to describe the property's data type. For example, a Dog
data type might be described by the following syntax:
{ // Dog
name: 'string',
age: 'integer'
}
This tells us that a dog has two properties, name
and age
, and that they should be a string
and integer
, respectively.
Optional properties
Some properties are optional, meaning that they can be represented by undefined
in javascript or null
in java or sql. This is represented by giving a ?
suffix to the property name. For example, a Dog
type like the one defined before could have an optional nickname, which might be described by the following syntax:
{ // Dog
name: 'string',
nickname?: 'string',
age: 'integer'
}
This tells us that a Dog
has a property nickname
that may be 'string' or may not be present at all.
Any properties without a ?
suffix should be considered required.
Keep in mind this is not valid javascript or JSON syntax, and that the ?
is not part of the property name.
Built-in Types
Some types, like 'string'
and 'integer
', mean exactly what you would expect them to - they refer to simple types common to both Java and JSON. Others, though, are less obvious, and some require different representations in Java, JSON, and SQL.
To ensure consistency, here is a quick overview of some of the common types used in this specification.
'string'
refers to a string of unicode characters, and can be represented by theString
types in all relevant languages'integer'
refers to a 32-bit signed integer, and can be represented by thenumber
type in JSON and theInteger
type in Java.'timestamp'
refers to a UNIX timestamp, i.e. the number of milliseconds since the beginning of the UNIX epoch - January 1, 1970. In JSON, this should be represented as a number, specifically along
. On the server side, as well as in the database, this should be represented as an instance ofjava.sql.Timestamp
.
Custom Types
Property types can also refer to types defined in this specification. For example, an owner for the Dog
type defined above might be described by the following syntax:
{ // Owner
dog: 'Dog'
}
This tells us that an Owner
has a property dog
that is described by the Dog
type, defined elsewhere in the specification.
Anonymous Types
Sometimes a type is never reused in the specification. In those cases, an object literal can be used to describe the type without naming it. For example, a ChewToy
data type might be described by the following syntax:
{ // ChewToy
material: 'string',
color: 'string',
dimensions: {
width: 'integer',
height: 'integer'
}
}
Here we could have defined a Dimensions
type with the following syntax:
{ // Dimensions
width: 'integer',
height: 'integer'
}
But if ChewToy
is the only type that makes use of Dimensions
, it's easier to define Dimensions
as an anonymous type.
Array Types
If a property should be an array of a specific type of element, it is represented as an array literal with the element type as a string inside the array. For example, a kennel with a list of dogs might be described by the following syntax:
{ // Kennel
dogs: ['Dog']
}
This tells us that a Kennel
has a property dogs
that is an array of elements, the type of each of which is described by the Dog
type
API Data Types
The semantics of the operations exposed by the API endpoints themselves are discussed in the following section, but in this section, the API data model is defined and the conceptual model for the application is explained in some depth. Additionally, some hints and constraints for the database model are discussed here.
In general, the data types defined here are in their general, read-only forms. That means that these are the versions of the models that are returned by GET
operations or nested inside other objects as auxiliary data. Most POST
operations, which often create new records in the database, require specialized versions of these models. Those special cases are covered by the endpoint specifications themselves unless otherwise noted.
User
A user of the application. The username
must be unique. The joined
timestamp should be assigned when the user is first created, and must never be updated.
{ // User
username: 'string',
profile: 'Profile',
joined: 'timestamp'
}
Profile
A user's profile information. Only the email
property is required.
{ // Profile
firstName?: 'string',
lastName?: 'string',
email: 'string',
phone?: 'string'
}
Credentials
A user's credentials. These are mostly used for validation and authentication during operations specific to a user. Passwords are plain text for the sake of academic simplicity, and it should be kept in mind that this is never appropriate in the real world.
{ // Credentials
username: 'string',
password: 'string'
}
Hashtag
A hashtag associated with tweets that contain its label. The label
property must be unique, but is case-insensitive. The firstUsed
timestamp should be assigned on creation, and must never be updated. The lastUsed
timestamp should be updated every time a new tweet is tagged with the hashtag.
{ // Hashtag
label: 'string',
firstUsed: 'timestamp',
lastUsed: 'timestamp'
}
Tweet
A tweet posted by a user. The posted
timestamp should be assigned when the tweet is first created, and must not be updated.
There are three distinct variations of tweets: simple, repost, and reply.
- A simple tweet has a
content
value but noinReplyTo
orrepostOf
values - A repost has a
repostOf
value but nocontent
orinReplyTo
values - A reply has
content
andinReplyTo
values, but norepostOf
value
{ // Tweet
id: 'integer'
author: 'User',
posted: 'timestamp',
content?: 'string',
inReplyTo?: 'Tweet',
repostOf?: 'Tweet'
}
Context
The reply context of a tweet. The before
property represents the chain of replies that led to the target
tweet, and the after
property represents the chain of replies that followed the target
tweet.
The chains should be in chronological order, and the after
chain should include all replies of replies, meaning that all branches of replies must be flattened into a single chronological list to fully satisfy the requirements.
{ // Context
target: 'Tweet',
before: ['Tweet'],
after: ['Tweet']
}
API Endpoints
GET validate/tag/exists/{label}
Checks whether or not a given hashtag exists.
Response
'boolean'
GET validate/username/exists/@{username}
Checks whether or not a given username exists.
Response
'boolean'
GET validate/username/available/@{username}
Checks whether or not a given username is available.
Response
'boolean'
GET users
Retrieves all active (non-deleted) users as an array.
Response
['User']
POST users
Creates a new user. If any required fields are missing or the username
provided is already taken, an error should be sent in lieu of a response.
If the given credentials match a previously-deleted user, re-activate the deleted user instead of creating a new one.
Request
{
credentials: 'Credentials',
profile: 'Profile'
}
Response
'User'
GET users/@{username}
Retrieves a user with the given username. If no such user exists or is deleted, an error should be sent in lieu of a response.
Response
'User'
PATCH users/@{username}
Updates the profile of a user with the given username. If no such user exists, the user is deleted, or the provided credentials do not match the user, an error should be sent in lieu of a response. In the case of a successful update, the returned user should contain the updated data.
Request
{
credentials: 'Credentials',
profile: 'Profile'
}
Response
'User'
DELETE users/@{username}
"Deletes" a user with the given username. If no such user exists or the provided credentials do not match the user, an error should be sent in lieu of a response. If a user is successfully "deleted", the response should contain the user data prior to deletion.
IMPORTANT: This action should not actually drop any records from the database! Instead, develop a way to keep track of "deleted" users so that if a user is re-activated, all of their tweets and information are restored.
Request
'Credentials'
Response
'User'
POST users/@{username}/follow
Subscribes the user whose credentials are provided by the request body to the user whose username is given in the url. If there is already a following relationship between the two users, no such followable user exists (deleted or never created), or the credentials provided do not match an active user in the database, an error should be sent as a response. If successful, no data is sent.
Request
'Credentials'
POST users/@{username}/unfollow
Unsubscribes the user whose credentials are provided by the request body from the user whose username is given in the url. If there is no preexisting following relationship between the two users, no such followable user exists (deleted or never created), or the credentials provided do not match an active user in the database, an error should be sent as a response. If successful, no data is sent.
Request
'Credentials'
GET users/@{username}/feed
Retrieves all (non-deleted) tweets authored by the user with the given username, as well as all (non-deleted) tweets authored by users the given user is following. This includes simple tweets, reposts, and replies. The tweets should appear in reverse-chronological order. If no active user with that username exists (deleted or never created), an error should be sent in lieu of a response.
Response
['Tweet']
GET users/@{username}/tweets
Retrieves all (non-deleted) tweets authored by the user with the given username. This includes simple tweets, reposts, and replies. The tweets should appear in reverse-chronological order. If no active user with that username exists (deleted or never created), an error should be sent in lieu of a response.
Response
['Tweet']
GET users/@{username}/mentions
Retrieves all (non-deleted) tweets in which the user with the given username is mentioned. The tweets should appear in reverse-chronological order. If no active user with that username exists, an error should be sent in lieu of a response.
A user is considered "mentioned" by a tweet if the tweet has content
and the user's username appears in that content following a @
.
Response
['Tweet']
GET users/@{username}/followers
Retrieves the followers of the user with the given username. Only active users should be included in the response. If no active user with the given username exists, an error should be sent in lieu of a response.
Response
['User']
GET users/@{username}/following
Retrieves the users followed by the user with the given username. Only active users should be included in the response. If no active user with the given username exists, an error should be sent in lieu of a response.
Response
['User']
GET tags
Retrieves all hashtags tracked by the database.
Response
['Hashtag']
GET tags/{label}
Retrieves all (non-deleted) tweets tagged with the given hashtag label. The tweets should appear in reverse-chronological order. If no hashtag with the given label exists, an error should be sent in lieu of a response.
A tweet is considered "tagged" by a hashtag if the tweet has content
and the hashtag's label appears in that content following a #
Response
['Tweet']
GET tweets
Retrieves all (non-deleted) tweets. The tweets should appear in reverse-chronological order.
Response
['Tweet']
POST tweets
Creates a new simple tweet, with the author set to the user identified by the credentials in the request body. If the given credentials do not match an active user in the database, an error should be sent in lieu of a response.
The response should contain the newly-created tweet.
Because this always creates a simple tweet, it must have a content
property and may not have inReplyTo
or repostOf
properties.
IMPORTANT: when a tweet with content
is created, the server must process the tweet's content for @{username}
mentions and #{hashtag}
tags. There is no way to create hashtags or create mentions from the API, so this must be handled automatically!
Request
{
content: 'string',
credentials: 'Credentials'
}
Response
'Tweet'
GET tweets/{id}
Retrieves a tweet with a given id. If no such tweet exists, or the given tweet is deleted, an error should be sent in lieu of a response.
Response
'Tweet'
DELETE tweets/{id}
"Deletes" the tweet with the given id. If no such tweet exists or the provided credentials do not match author of the tweet, an error should be sent in lieu of a response. If a tweet is successfully "deleted", the response should contain the tweet data prior to deletion.
IMPORTANT: This action should not actually drop any records from the database! Instead, develop a way to keep track of "deleted" tweets so that even if a tweet is deleted, data with relationships to it (like replies and reposts) are still intact.
Request
'Credentials'
Response
'Tweet'
POST tweets/{id}/like
Creates a "like" relationship between the tweet with the given id and the user whose credentials are provided by the request body. If the tweet is deleted or otherwise doesn't exist, or if the given credentials do not match an active user in the database, an error should be sent. Following successful completion of the operation, no response body is sent.
Request
'Credentials'
POST tweets/{id}/reply
Creates a reply tweet to the tweet with the given id. The author of the newly-created tweet should match the credentials provided by the request body. If the given tweet is deleted or otherwise doesn't exist, or if the given credentials do not match an active user in the database, an error should be sent in lieu of a response.
Because this creates a reply tweet, content is not optional. Additionally, notice that the inReplyTo
property is not provided by the request. The server must create that relationship.
The response should contain the newly-created tweet.
IMPORTANT: when a tweet with content
is created, the server must process the tweet's content for @{username}
mentions and #{hashtag}
tags. There is no way to create hashtags or create mentions from the API, so this must be handled automatically!
Request
{
content: 'string',
credentials: 'Credentials'
}
Response
'Tweet'
POST tweets/{id}/repost
Creates a repost of the tweet with the given id. The author of the repost should match the credentials provided in the request body. If the given tweet is deleted or otherwise doesn't exist, or the given credentials do not match an active user in the database, an error should be sent in lieu of a response.
Because this creates a repost tweet, content is not allowed. Additionally, notice that the repostOf
property is not provided by the request. The server must create that relationship.
The response should contain the newly-created tweet.
Request
'Credentials'
Response
'Tweet'
GET tweets/{id}/tags
Retrieves the tags associated with the tweet with the given id. If that tweet is deleted or otherwise doesn't exist, an error should be sent in lieu of a response.
IMPORTANT Remember that tags and mentions must be parsed by the server!
Response
['Hashtag']
GET tweets/{id}/likes
Retrieves the active users who have liked the tweet with the given id. If that tweet is deleted or otherwise doesn't exist, an error should be sent in lieu of a response.
Deleted users should be excluded from the response.
Response
['User']
GET tweets/{id}/context
Retrieves the context of the tweet with the given id. If that tweet is deleted or otherwise doesn't exist, an error should be sent in lieu of a response.
IMPORTANT: While deleted tweets should not be included in the before
and after
properties of the result, transitive replies should. What that means is that if a reply to the target of the context is deleted, but there's another reply to the deleted reply, the deleted reply should be excluded but the other reply should remain.
Response
'Context'
GET tweets/{id}/replies
Retrieves the direct replies to the tweet with the given id. If that tweet is deleted or otherwise doesn't exist, an error should be sent in lieu of a response.
Deleted replies to the tweet should be excluded from the response.
Response
['Tweet']
GET tweets/{id}/reposts
Retrieves the direct reposts of the tweet with the given id. If that tweet is deleted or otherwise doesn't exist, an error should be sent in lieu of a response.
Deleted reposts of the tweet should be excluded from the response.
Response
['Tweet']
GET tweets/{id}/mentions
Retrieves the users mentioned in the tweet with the given id. If that tweet is deleted or otherwise doesn't exist, an error should be sent in lieu of a response.
Deleted users should be excluded from the response.
IMPORTANT Remember that tags and mentions must be parsed by the server!
Response
['User']