Contracts - Memory-Lane-COS301/miniproject-2023 GitHub Wiki

COS 301 - Mini Project Contracts

This document will serve as the single source of truth for all established contracts. It is an ongoing collaboration between frontend, backend and integration teams, and must be regularly reviewed to guarantee that the contract specifications remain up-to-date and meet the requirements of both teams.

The interfaces to be used by both the backend and frontend will be defined in the libs/api directory.

  • Interfaces are defined under libs/api/feature/util/interfaces
  • Requests are defined under libs/api/feature/util/requests
  • Responses are defined under libs/api/feature/util/responses

Under the Interfaces section, you’ll find definitions of the interfaces. In the Endpoints section, you’ll find examples of how to use these interfaces, including example requests and responses.

Conventions

Use CRUD terminology, such as creating, updating, and deleting, instead of conventions like editing or removing.

Some examples:

  • UpdateProfile instead of EditProfile
  • DeleteProfile instead of RemoveProfile

Interfaces

Users

@mp/api/users/util

IUser {
  userId: string;
  name?: string | null | undefined;
  surname?: string | null | undefined;
  username?: string | null | undefined;
  email?: string | null | undefined;
  profileImgUrl?: string | null | undefined;
  bio?: string | null | undefined;
  friendCount?: number | null | undefined;
  memoryCount?: number | null | undefined;
  accountTime?: number | null | undefined;
  lastOnline?: timestamp | null | undefined;
  online?: boolean  | null | undefined; // requires clarification
  created?: Timestamp | null | undefined;
  // ... any other metadata
}
Requests 
IGetUserRequest {
  user: IUser
}
IUpdateUserRequest {
  user: IUser
}
IDeleteUserRequest {
  user: IUser
}
Responses 
IGetUserResponse {
  user: IUser
}
IUpdateUserResponse {
  user: IUser
}
IDeleteUserResponse {
  user: IUser
}

Profiles

@mp/api/profiles/util

IProfile {
  user: IUser;
  memories: IMemories[];
}
Requests 
IGetProfileRequest {
  user: IUser
}
Responses 
IGetProfileResponse {
  profile: IProfile
}

Memories

@mp/api/memories/util

IMemory {
  userId?: string | null | undefined;
  memoryId?: string | null | undefined;
  username?: string | null | undefined;
  title?: string | null | undefined;
  description?: string | null | undefined;
  imgUrl?: string | null | undefined;
  profileImgUrl?: string | null | undefined;
  created?: Timestamp | null | undefined;
  commentsCount?: number | null | undefined
  remainingTime?: number | null | undefined
  alive?: boolean | null | undefined;
  comments?: IComment[] | null | undefined;
  // ... any other metadata
}
Requests 
ICreateMemoryRequest {
  memory: IMemory
}
IGetFeedMemoriesRequest {
  user: IUser
}
Responses 
ICreateMemoryResponse {
  memory: IMemory
}
IGetFeedMemoriesResponse {
  memory: IMemory[]
}

Comments

@mp/api/memories/util

IComment {
  userId?: string | null | undefined;
  memoryId? : string | null | undefined;
  commentId?: string | null | undefined;
  username?: string | null | undefined;
  profileImgUrl: string | null | undefined;
  text: string | null | undefined;
  created: Timestamp | null | undefined;
}
Requests 
IGetCommentsRequest {
  memory: IMemory;
}
ICreateCommentRequest {
  comment: IComment;
}
IUpdateCommentRequest {
  comment: IComment;
}
Responses 
IGetCommentsResponse {
  comment: IComment;
}
ICreateCommentResponse {
  comment: IComment;
}
IUpdateCommentResponse {
  comment: IComment;
}

Friend Requests

@mp/api/friends/util

IFriendRequest {
  senderId?: string | null | undefined;
  receiverId?: string | null | undefined;
  receiverUsername?: string | null | undefined;
  status?: FriendRequestStatus | null | undefined;
  lastUpdated?: Timestamp | null | undefined;
  created?: Timestamp | null | undefined;
}
enum FriendRequestStatus {
  PENDING = 'pending',
  ACCEPTED = 'accepted',
  REJECTED = 'rejected',
}
Requests 
ICreateFriendRequest {
  friendRequest: IFriendRequest;
}
IUpdateFriendRequest {
  friendRequest: IFriendRequest;
}
Responses

Cloud Function Endpoints

Users

getUser(Bandisa)🟢
Request
IGetUserRequest {
  user: {
    userId: "0104fa66-5a7b-429c-aedd-acab833be72e"
  }
}
Response
{    
  userId: '0104fa66-5a7b-429c-aedd-acab833be72e',
  name: 'Dena',
  surname: 'Champlin',
  username: 'Dena52',
  email: '[email protected]',
  profileImgUrl: 'https://cloudflare-ipfs.com/ipfs/Qmd3W5DuhgHirLHGVixi6V76LhCkZUz6pnFt5AJBiyvHye/avatar/508.jpg',
  bio: 'Veniam numquam adipisci debitis numquam tenetur velit nam culpa id.',
  friendCount: 0,
  memoryCount: 0,
  accountTime: 86400,
  lastOnline: Timestamp { _seconds: 1681561082, _nanoseconds: 889000000 },
  online: false,
  created: Timestamp { _seconds: 1681561082, _nanoseconds: 889000000 }
}
updateUser(Armand) 🟢

Profiles

getUserProfile (Luca) 🟢
Request
IGetProfileRequest {
 user: {
      userId: "094723h5ujfdo072o3urhqev", // for verification
      username: "JohnDoe" // retrieve the profile of a user by their username
    }
}
Response
IGetProfileResponse {
  profile: {
    user: {
      name: 'John',
      surname: 'Doe',
      username: 'JohnDoe',
      email: '[email protected]',
      profileImgUrl: 'https://bit.ly/3MCrcnB',
      bio: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit',
      friendCount: 5,
      memoryCount: 5,
      accountTime: 1834193284,
      lastOnline: 1618582394,
      online: true,
      created: {
        seconds: 1681561083,
        nanoseconds: 605000000,
      },
    },
    memories: [
      {
        username: 'JohnDoe',
        title: 'Summer Holiday',
        description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit',
        imgUrl: 'https://bit.ly/3MCrcnB',
        profileImgUrl: 'https://bit.ly/3MCrcnB',
        created: {
          seconds: 1681561083,
          nanoseconds: 605000000,
        },
        commentsCount: 5,
        remainingTime: 1834193284,
        alive: true,
        comments: [
          {
            commentId: 'adfjh9871r71oui43hfq0d7y6',
            username: 'JohnDoe',
            profileImgUrl: 'https://bit.ly/3MCrcnB',
            text: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit',
            created: 1618582394,
          }
        ]
      },
    ]
  }
}
getDeadMemories(Luca)🟢
Request
IGetProfileRequest {
 user: {
      userId: "094723h5ujfdo072o3urhqev", // for verification
      username: "JohnDoe" // retrieve the profile of a user by their username
    }
}
Response
IGetProfileResponse {
  profile: {
    userId: "056510d6-35ba-4794-98e4-70a7e77e745b",
          memories: [
              {
                  "imgUrl": "https://loremflickr.com/640/480",
                  "alive": false,
                  "created": {
                      "_seconds": 1681545411,
                      "_nanoseconds": 71000000
                  },
                  "commentsCount": 5,
                  "profileImgUrl": "https://cloudflare-ipfs.com/ipfs/Qmd3W5DuhgHirLHGVixi6V76LhCkZUz6pnFt5AJBiyvHye/avatar/246.jpg",
                  "description": "Adipisci veniam alias eius quibusdam. Corrupti minus repellat dolorum atque quis. Illo consequatur temporibus nisi itaque velit repellat. Doloribus nemo aspernatur ratione minima ipsa fuga alias eligendi tempora.",
                  "memoryId": "016d1c8a-bbaf-4b90-ac36-ab2cab153675",
                  "title": "excepturi saepe fugiat",
                  "username": "Celine_Volkman",
                  "remainingTime": 3600,
                  "comments": [
                      {
                          "created": {
                              "_seconds": 1681545411,
                              "_nanoseconds": 71000000
                          },
                          "profileImgUrl": "https://cloudflare-ipfs.com/ipfs/Qmd3W5DuhgHirLHGVixi6V76LhCkZUz6pnFt5AJBiyvHye/avatar/205.jpg",
                          "commentId": "3c2b85de-4f98-4a4b-bca4-8981c873e8a2",
                          "text": "Labore eveniet hic consectetur. Unde ut nobis. Consectetur harum laboriosam.",
                          "username": "Audrey69"
                      },
                  ]
              }
  		]
              
          user: null
      }
}

Memories

getFeedMemories Armand 🟢
Request
IGetFeedMemoriesRequest {
    user: {
        userId: '97841uqejdf178rgab4'
    }
}
Response
IGetFeedMemoriesResponse {
  memories: [
     {
        memoryId: '19o4872yqwouhadsjcvs9d8vy',
        username: 'JohnDoe',
        title: 'Summer Holiday',
        description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit',
        imgUrl: 'https://bit.ly/3MCrcnB',
        profileImgUrl: 'https://bit.ly/3MCrcnB',
        created: {
          seconds: 1681561083,
          nanoseconds: 605000000
        },
        commentsCount: 0,
        remainingTime: 1834193284,
        alive: true,
     } 
  ]
}
reviveDeadMemories(Luca) 🟢
(Note: for exclusive use to revive a dead memory, not updating a memories time)
Request
IReviveDeadMemoryRequest {
  request:{
          userId: "056510d6-35ba-4794-98e4-70a7e77e745b",
          memoryId: "015317a7-cc81-4be1-807a-1f468b7bff7f",
          secondsToAdd: 3600
      }
}
Response
IReviveDeadMemoryResponse {
   status: "success"
}
updateMemoryTime(Luca) 🟢
(Note: for exclusive use to add time to a memory)
Request
IUpdateMemoryTimeRequest {
  request:{
          userId: "056510d6-35ba-4794-98e4-70a7e77e745b",
          memoryId: "015317a7-cc81-4be1-807a-1f468b7bff7f",
          secondsToAdd: 3600
      }
}
Response
IUpdateMemoryTimeResponse {
   status: "success"
}
createMemory (Bandisa)🟢
Request
ICreateMemoryRequest {
  memory: {
    userId: '97841uqejdf178rgab4',
    title: 'Summer Holiday',
    description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit',
    imgUrl: 'https://bit.ly/3MCrcnB', // optional, will be generated
  }
}
Response
ICreateMemoryResponse {
  memory: {
    username: 'JohnDoe',
    title: 'Summer Holiday',
    description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit',
    imgUrl: 'https://bit.ly/3MCrcnB',
    profileImgUrl: 'https://bit.ly/3MCrcnB',
    created: {
      seconds: 1681561083,
      nanoseconds: 605000000
    },
    commentsCount: 0,
    remainingTime: 1834193284,
    alive: true,
  }
}

Comments

getComments (Armand) 🟢
Request
IGetCommentsRequest {
  memory: {
    userId: '97841uqejdf178rgab4',
    memoryId: '1184e98451o3phtadfsjlf',
  }
}
Response
IGetCommentsResponse {
  comments: [
      {
        commentId: 'adfjh9871r71oui43hfq0d7y6',
        username: 'JohnDoe',
        profileImgUrl: 'https://bit.ly/3MCrcnB',
        text: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit',
        created: {
          seconds: 1681561083,
          nanoseconds: 605000000,
        },
      }
  ]
}
createComment (Armand) 🟢
Request
ICreateCommentRequest {
  comment: {
    userId: '97841uqejdf178rgab4',
    memoryId: '1184e98451o3phtadfsjlf',
    text: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit',
  }
}
Response
ICreateCommentResponse {
  comment: {
    memoryId: '1184e98451o3phtadfsjlf',
    commentId: 'adfjh9871r71oui43hfq0d7y6',
    username: 'JohnDoe',
    profileImgUrl: 'https://bit.ly/3MCrcnB',
    text: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit',
    created: {
      seconds: 1681561083,
      nanoseconds: 605000000,
    },
  }
}
updateComment (Armand)

Friend Requests

createFriendRequest (Luca) 🟢
Request
IUpdateFriendRequest {
  friendRequest: {
    senderId: "094723h5ujfdo072o3urhqev"
    receiverUsername: "Javonte_Klein"
  }
}
Response
IUpdateFriendResponse {
  status: "success"
}
updateFriendRequest(Luca) 🟢
Request
IUpdateFriendRequest {
  friendRequest: {
    senderId: "094723h5ujfdo072o3urhqev",
    receiverUsername: "Javonte_Klein",
    status: "accepted"
  }
}
Response
IUpdateFriendResponse {
  status: "success"
}
deleteFriendRequest(Luca) 🟢
(note: that this is used to cansel a freindRequest sent to someone)
Request
IDeleteFriendRequest {
  friendRequest: {
    senderId: "094723h5ujfdo072o3urhqev",
    receiverUsername: "Javonte_Klein",
  }
}
Response
IDeleteFriendResponse {
  status: "success"
}
deleteFriend(Luca) 🟢
(note: that this is used to unfriend someone)
Request
IDeleteFriendRequest {
  friendRequest: {
    senderId: "094723h5ujfdo072o3urhqev",
    receiverUsername: "Javonte_Klein",
  }
}
Response
IDeleteFriendResponse {
  status: "success"
}
getFriends(Luca)🟢
(note: this is used to get all the friends their memories and comments of a user)
Request
IGetFriendsRequest {
  user:{
          "senderId": "0a3f7351-5d2b-468c-a1f5-7980a46acb8a"
      }
}
Response
IGetFriendsResponse {
 profiles: [
          {
              userId: "0b11853b-c5ab-4006-b89f-4bad0e16bccc",
              memories: [
                  {
                      "imgUrl": "https://loremflickr.com/640/480",
                      "alive": true,
                      "created": {
                          "_seconds": 1681545411,
                          "_nanoseconds": 70000000
                      },
                      "commentsCount": 5,
                      "profileImgUrl": "https://cloudflare-ipfs.com/ipfs/Qmd3W5DuhgHirLHGVixi6V76LhCkZUz6pnFt5AJBiyvHye/avatar/92.jpg",
                      "description": "Alias saepe ipsum accusamus repellat eaque enim minus quidem qui. Repellendus numquam eum dicta veniam qui beatae. Illo voluptates blanditiis illum quos maxime.",
                      "memoryId": "d1317c5c-1e61-42a4-b4f7-85fada8a3a79",
                      "title": "cupiditate suscipit praesentium",
                      "username": "Dariana_Ziemann36",
                      "remainingTime": 3600,
                      "comments": [
                          {
                              "created": {
                                  "_seconds": 1681545411,
                                  "_nanoseconds": 70000000
                              },
                              "profileImgUrl": "https://cloudflare-ipfs.com/ipfs/Qmd3W5DuhgHirLHGVixi6V76LhCkZUz6pnFt5AJBiyvHye/avatar/1004.jpg",
                              "commentId": "65848892-bd09-4aa0-9db8-d007a6761410",
                              "text": "Dolorem quod dolorum. Repellendus soluta veritatis maxime voluptatibus debitis sint. Inventore facilis blanditiis voluptate autem occaecati occaecati ea. Rerum quibusdam numquam atque.",
                              "username": "Albertha29"
                          }
                      ]
                  },
                  {
                      "imgUrl": "https://loremflickr.com/640/480",
                      "alive": true,
                      "created": {
                          "_seconds": 1681545411,
                          "_nanoseconds": 79000000
                      },
                      "commentsCount": 5,
                      "profileImgUrl": "https://cloudflare-ipfs.com/ipfs/Qmd3W5DuhgHirLHGVixi6V76LhCkZUz6pnFt5AJBiyvHye/avatar/92.jpg",
                      "description": "Consequuntur blanditiis tenetur odit. Quisquam amet consectetur consectetur fugiat natus fugit tempora neque molestias. Nobis rem praesentium soluta earum. Rerum error ea ullam reiciendis magnam impedit esse. Iusto asperiores sint sint animi adipisci non nisi et. Excepturi harum id veniam fuga necessitatibus.",
                      "memoryId": "24a82acc-575f-4fd7-ac05-6301900ec942",
                      "title": "unde nulla suscipit",
                      "username": "Dariana_Ziemann36",
                      "remainingTime": 3600,
                      "comments": [
                          {
                              "created": {
                                  "_seconds": 1681545411,
                                  "_nanoseconds": 79000000
                              },
                              "profileImgUrl": "https://cloudflare-ipfs.com/ipfs/Qmd3W5DuhgHirLHGVixi6V76LhCkZUz6pnFt5AJBiyvHye/avatar/853.jpg",
                              "commentId": "2223562d-aacb-49be-9381-29ce587e39d5",
                              "text": "Vero mollitia temporibus vitae quibusdam quasi distinctio.",
                              "username": "Heloise13"
                          }
                      ]
                  },
                  {
                      "imgUrl": "https://loremflickr.com/640/480",
                      "alive": true,
                      "created": {
                          "_seconds": 1681545411,
                          "_nanoseconds": 85000000
                      },
                      "commentsCount": 5,
                      "profileImgUrl": "https://cloudflare-ipfs.com/ipfs/Qmd3W5DuhgHirLHGVixi6V76LhCkZUz6pnFt5AJBiyvHye/avatar/92.jpg",
                      "description": "Numquam impedit nemo excepturi molestiae itaque reprehenderit incidunt aut a. Occaecati ducimus pariatur ab ullam nobis adipisci expedita amet. Perspiciatis dolore pariatur odio. Eaque quidem minus rerum minus sunt id id consectetur mollitia. Culpa quasi atque asperiores.",
                      "memoryId": "2b449e61-7ea4-42ce-9fe9-01a9a7a15f2a",
                      "title": "culpa esse voluptate",
                      "username": "Dariana_Ziemann36",
                      "remainingTime": 3600,
                      "comments": [
                          {
                              "created": {
                                  "_seconds": 1681545411,
                                  "_nanoseconds": 85000000
                              },
                              "profileImgUrl": "https://cloudflare-ipfs.com/ipfs/Qmd3W5DuhgHirLHGVixi6V76LhCkZUz6pnFt5AJBiyvHye/avatar/1015.jpg",
                              "commentId": "dfcce906-f8ae-4a5d-8619-32c3ef2b9261",
                              "text": "Quae alias laboriosam optio aspernatur eius odio placeat. Ad enim nulla.",
                              "username": "Dillan_Wilderman"
                          }
                      ]
                  }
              ],
              user: {
                  "friendCount": 0,
                  "created": {
                      "_seconds": 1681545410,
                      "_nanoseconds": 794000000
                  },
                  "bio": "Provident odit magnam.",
                  "memoryCount": 0,
                  "userId": "",
                  "surname": "Ziemann",
                  "profileImgUrl": "https://cloudflare-ipfs.com/ipfs/Qmd3W5DuhgHirLHGVixi6V76LhCkZUz6pnFt5AJBiyvHye/avatar/92.jpg",
                  "name": "Dariana",
                  "online": false,
                  "accountTime": 86400,
                  "lastOnline": {
                      "_seconds": 1681545410,
                      "_nanoseconds": 794000000
                  },
                  "email": "[email protected]",
                  "username": "Dariana_Ziemann36"
              }
          },
}
getAllPendingFriendRequests(Luca) 🟢
(note: this is used to get all users's pending friend requests)
Request
IGetPendingFriendRequest {
  user:{
          senderId: "0a3f7351-5d2b-468c-a1f5-7980a46acb8a"
      }
}
Response
IGetPendingFriendResponse {
            profiles: [
          {
              "userId": "0b11853b-c5ab-4006-b89f-4bad0e16bccc",
              "user": {
                  "friendCount": 0,
                  "created": {
                      "_seconds": 1681545410,
                      "_nanoseconds": 794000000
                  },
                  "bio": "Provident odit magnam.",
                  "memoryCount": 0,
                  "userId": "",
                  "surname": "Ziemann",
                  "profileImgUrl": "https://cloudflare-ipfs.com/ipfs/Qmd3W5DuhgHirLHGVixi6V76LhCkZUz6pnFt5AJBiyvHye/avatar/92.jpg",
                  "name": "Dariana",
                  "online": false,
                  "accountTime": 86400,
                  "lastOnline": {
                      "_seconds": 1681545410,
                      "_nanoseconds": 794000000
                  },
                  "email": "[email protected]",
                  "username": "Dariana_Ziemann36"
              }
          },
          {
              "userId": "0a3f7351-5d2b-468c-a1f5-7980a46acb8a",
              "user": {
                  "friendCount": 0,
                  "created": {
                      "_seconds": 1681545410,
                      "_nanoseconds": 794000000
                  },
                  "bio": "Rerum ad quaerat.",
                  "memoryCount": 0,
                  "userId": "",
                  "surname": "Paucek",
                  "profileImgUrl": "https://cloudflare-ipfs.com/ipfs/Qmd3W5DuhgHirLHGVixi6V76LhCkZUz6pnFt5AJBiyvHye/avatar/706.jpg",
                  "name": "Jewell",
                  "online": false,
                  "accountTime": 86400,
                  "lastOnline": {
                      "_seconds": 1681545410,
                      "_nanoseconds": 794000000
                  },
                  "email": "[email protected]",
                  "username": "Jewell36"
              }
          }
      ]
}

API Events

Users

Profiles

Memories

Comments

CommentCreated (Armand) 🟢

Will persist the comment to Firestore. Will be picked up by a memory saga to increment comment counter.

Friend Requests

App Page Interactions

Home Feed

Profile

Search

Notifications

Database

Users

/users/{userId}
  name: string
  surname: string
  username: string
  email: string
  profileImgUrl: string
  bio: string
  friendCount: number
  memoryCount: number
  accountTime: number
  lastOnline: timestamp
  online: boolean // requires clarification
  created: Timestamp
  // ... any other metadata

Memories

/memories/{memoryId}
  userId: string
  username: string // Debatable, might join on userId to get username
  title: string
  description: string
  imgUrl: string
  profileImgUrl: string // Debatable, might join on userId to get profile
  created: Timestamp
  commentsCount: number
  remainingTime: number
  alive: boolean
  // ... any other metadata
  /comments/{commentId}
    userId: string
    username: string // Debatable, might join on userId to get username
    profileImgUrl: string // Debatable, might join on userId to get profile
    text: string
    created: Timestamp

Friend Requests

/friendRequests/{friendRequestId}
  senderId: string
  receiverId: string
  status: string ('pending', 'accepted', 'rejected')
  created: Timestamp

Friends

/friends/{friendId}
  userId1: string
  userId2: string
  created: Timestamp
⚠️ **GitHub.com Fallback** ⚠️