diff --git a/backend/api.yaml b/backend/api.yaml index 6e6433c5..0e60bbd3 100644 --- a/backend/api.yaml +++ b/backend/api.yaml @@ -9,158 +9,84 @@ servers: description: Local server paths: - /auth/logout: - post: - operationId: logout - description: Invalidates current token. + /: + get: + operationId: getRoot + description: Root of API tags: - - Auth + - Miscellaneous responses: - '200': + "200": description: OK content: - application/json: + text/plain: schema: - properties: - messages: - type: string - example: Successfully logged out. - /user: + type: string + example: Join DevSoc! https://devsoc.app/ + + /auth/callback/google: get: - operationId: getLoggedInUser - description: Returns info about currently logged in user. + operationId: googleCallback + description: Google OAuth callback tags: - - User + - Auth + parameters: + - name: code + in: query + description: Google OAuth code + required: true + schema: + type: string responses: - '200': - description: OK - content: - application/json: - schema: - properties: - id: - type: integer - format: int64 - example: 1541815603606036480 - email: - type: string - example: me@example.com - zid: - type: string - example: z5555555 - name: - type: string - example: Clancy Lion - degree_name: - type: string - example: Computer Science - degree_starting_year: - type: integer - example: 2024 - role: - type: string - example: User - '401': - description: Not logged in. + "200": + description: Ok content: - application/json: - schema: - properties: - error: - type: string - example: Not logged in. - delete: - operationId: deleteUserById - description: Deletes currently logged in user. + /auth/logout: + post: + operationId: logout + description: Invalidates current token tags: - - User + - Auth responses: - '200': - description: OK + "200": + description: Ok content: application/json: schema: properties: message: type: string - example: Successfully deleted user. - '403': - description: User is only admin of an organisation. - content: - application/json: - schema: - properties: - error: - type: string - example: "Cannot delete sole admin of an organisation." - '401': - description: Not logged. + example: Successfully logged out + "401": + description: Not logged in content: application/json: schema: - properties: - error: - type: string - example: Not logged in. - /user/{id}: + $ref: "#/components/schemas/NotLoggedIn" + + /user: get: - operationId: getUserById - parameters: - - name: id - in: path - description: User ID - required: true - schema: - type: integer - format: int64 - description: Returns info about specified user. + operationId: getLoggedInUser + description: Returns info about currently logged in user tags: - User responses: - '200': + "200": description: OK content: application/json: schema: - properties: - id: - type: integer - format: int64 - example: 1541815603606036480 - email: - type: string - example: me@example.com - zid: - type: string - example: z5555555 - name: - type: string - example: Clancy Lion - pronouns: - type: string - example: They/Them - gender: - type: string - example: Male - degree_name: - type: string - example: Computer Science - degree_starting_year: - type: integer - example: 2024 - '403': - description: Requested user has not applied to one of authorized user's campaign. + $ref: "#/components/schemas/User" + "401": + description: Not logged in content: application/json: schema: - properties: - error: - type: string - example: "Insufficient permissions" + $ref: "#/components/schemas/NotLoggedIn" /user/name: patch: operationId: updateUserName - description: Updates currently logged in user's name. + description: Updates currently logged in user's name tags: - User requestBody: @@ -173,7 +99,7 @@ paths: type: string example: "Clancy Tiger" responses: - '200': + "200": description: OK content: application/json: @@ -181,21 +107,17 @@ paths: properties: message: type: string - example: Successfully updated name. - '401': + example: Successfully updated name + "401": description: Not logged in. content: application/json: schema: - properties: - error: - type: string - example: Not logged in. - + $ref: "#/components/schemas/NotLoggedIn" /user/pronouns: patch: operationId: updateUserPronouns - description: Updates currently logged in user's pronouns. + description: Updates currently logged in user's pronouns tags: - User requestBody: @@ -204,11 +126,11 @@ paths: application/json: schema: properties: - zid: + pronouns: type: string - example: "z5123456" + example: They/Them responses: - '200': + "200": description: OK content: application/json: @@ -216,20 +138,17 @@ paths: properties: message: type: string - example: Successfully updated pronouns. - '401': + example: Successfully updated pronouns + "401": description: Not logged in. content: application/json: schema: - properties: - error: - type: string - example: Not logged in. + $ref: "#/components/schemas/NotLoggedIn" /user/gender: patch: operationId: updateUserGender - description: Updates currently logged in user's gender. + description: Updates currently logged in user's gender tags: - User requestBody: @@ -238,11 +157,11 @@ paths: application/json: schema: properties: - zid: + gender: type: string - example: "z5123456" + example: Female responses: - '200': + "200": description: OK content: application/json: @@ -250,22 +169,17 @@ paths: properties: message: type: string - example: Successfully updated gender. - '401': + example: Successfully updated gender + "401": description: Not logged in. content: application/json: schema: - properties: - error: - type: string - example: Not logged in. - - + $ref: "#/components/schemas/NotLoggedIn" /user/zid: patch: operationId: updateUserZid - description: Updates currently logged in user's zID. + description: Updates currently logged in user's zID tags: - User requestBody: @@ -276,9 +190,9 @@ paths: properties: zid: type: string - example: "z5123456" + example: z5123456 responses: - '200': + "200": description: OK content: application/json: @@ -286,20 +200,17 @@ paths: properties: message: type: string - example: Successfully updated zID. - '401': + example: Successfully updated zID + "401": description: Not logged in. content: application/json: schema: - properties: - error: - type: string - example: Not logged in. + $ref: "#/components/schemas/NotLoggedIn" /user/degree: patch: operationId: updateUserDegree - description: Updates currently logged in user's degree. + description: Updates currently logged in user's degree tags: - User requestBody: @@ -310,12 +221,12 @@ paths: properties: degree_name: type: string - example: "Electrical Engineering" + example: Electrical Engineering degree_starting_year: type: integer example: 2024 responses: - '200': + "200": description: OK content: application/json: @@ -323,25 +234,21 @@ paths: properties: message: type: string - example: Successfully updated email. - '401': + example: Successfully updated email + "401": description: Not logged in. content: application/json: schema: - properties: - error: - type: string - example: Not logged in. - + $ref: "#/components/schemas/NotLoggedIn" /user/applications: get: operationId: getUserApplications - description: Returns info about applications made by currently logged in user. + description: Returns info about applications made by currently logged in user tags: - User responses: - '200': + "200": description: OK content: application/json: @@ -350,23 +257,18 @@ paths: campaigns: type: array items: - $ref: '#/components/schemas/ApplicationDetails' - '401': + $ref: "#/components/schemas/ApplicationDetails" + "401": description: Not logged in. content: application/json: schema: - properties: - error: - type: string - example: Not logged in. - - + $ref: "#/components/schemas/NotLoggedIn" /organisation: post: operationId: createOrganisation - description: Creates a new organisation. + description: Create a new organisation tags: - Organisation requestBody: @@ -375,16 +277,20 @@ paths: application/json: schema: properties: + slug: + type: string + description: ASCII string for URL like https://chaos.csesoc.app/s/unsw-devsoc + example: unsw-devsoc name: type: string - example: "UNSW Software Development Society" + example: UNSW Software Development Society admin: type: integer format: int64 example: 1541815603606036480 description: User ID of admin responses: - '200': + "200": description: OK content: application/json: @@ -392,16 +298,44 @@ paths: properties: message: type: string - example: Successfully created organisation. - '403': - description: User is not a super user. + example: Successfully created organisation + "403": + description: User is not a SuperUser + content: + application/json: + schema: + $ref: "#/components/schemas/Unauthorized" + /organisation/slug_check: + post: + operationId: checkOrganisationSlugAvailability + description: Check if slug is available + tags: + - Organisation + requestBody: + required: true + content: + application/json: + schema: + properties: + slug: + type: string + example: unsw-devsoc + responses: + "200": + description: OK content: application/json: schema: properties: - error: + message: type: string - example: Unauthorized + example: Organisation slug is available + "400": + description: Bad request - slug is in use or not ASCII + content: + application/json: + schema: + $ref: "#/components/schemas/BadRequest" /organisation/{id}: get: operationId: getOrganisationById @@ -417,7 +351,7 @@ paths: tags: - Organisation responses: - '200': + "200": description: OK content: application/json: @@ -436,7 +370,7 @@ paths: created_at: type: string example: 2024-02-10T18:25:43.511Z - '401': + "401": description: Not logged in. content: application/json: @@ -459,7 +393,7 @@ paths: tags: - Organisation responses: - '200': + "200": description: OK content: application/json: @@ -468,7 +402,7 @@ paths: message: type: string example: Successfully deleted organisation. - '401': + "401": description: Not logged in. content: application/json: @@ -477,7 +411,7 @@ paths: error: type: string example: Not logged in. - '403': + "403": description: User is not a super user. content: application/json: @@ -501,7 +435,7 @@ paths: tags: - Organisation responses: - '200': + "200": description: OK content: application/json: @@ -510,8 +444,8 @@ paths: campaigns: type: array items: - $ref: '#/components/schemas/OrganisationCampaign' - '401': + $ref: "#/components/schemas/OrganisationCampaign" + "401": description: Not logged in. content: application/json: @@ -536,7 +470,7 @@ paths: tags: - Organisation responses: - '200': + "200": description: OK content: application/json: @@ -546,7 +480,7 @@ paths: type: string description: Presigned S3 url to upload file. example: https://www.youtube.com/watch?v=dQw4w9WgXcQ - '401': + "401": description: Not logged in. content: application/json: @@ -555,7 +489,7 @@ paths: error: type: string example: Not logged in. - '403': + "403": description: User is not an organisation admin. content: application/json: @@ -580,7 +514,7 @@ paths: tags: - Organisation responses: - '200': + "200": description: OK content: application/json: @@ -601,7 +535,7 @@ paths: role: type: string example: Admin - '403': + "403": description: User is not an organisation admin or member. content: application/json: @@ -632,12 +566,17 @@ paths: items: type: integer format: int64 - example: [1541815603606036480, 1541815603606036827, 1541815287306036429] + example: + [ + 1541815603606036480, + 1541815603606036827, + 1541815287306036429, + ] description: Specifies members for specified organistion. tags: - Organisation responses: - '200': + "200": description: OK content: application/json: @@ -646,7 +585,7 @@ paths: message: type: string example: Successfully updated members. - '401': + "401": description: Not logged in. content: application/json: @@ -655,7 +594,7 @@ paths: error: type: string example: Not logged in. - '403': + "403": description: User is not an organisation admin. content: application/json: @@ -687,7 +626,7 @@ paths: tags: - Organisation responses: - '200': + "200": description: OK content: application/json: @@ -696,7 +635,7 @@ paths: message: type: string example: Successfully updated members. - '401': + "401": description: Not logged in. content: application/json: @@ -705,7 +644,7 @@ paths: error: type: string example: Not logged in. - '403': + "403": description: User is not an organisation admin. content: application/json: @@ -730,7 +669,7 @@ paths: tags: - Organisation responses: - '200': + "200": description: OK content: application/json: @@ -751,7 +690,7 @@ paths: role: type: string example: Admin - '403': + "403": description: User is not a SuperUser. content: application/json: @@ -782,12 +721,17 @@ paths: items: type: integer format: int64 - example: [1541815603606036480, 1541815603606036827, 1541815287306036429] + example: + [ + 1541815603606036480, + 1541815603606036827, + 1541815287306036429, + ] description: Specifies Admins for specified organistion. tags: - Organisation responses: - '200': + "200": description: OK content: application/json: @@ -796,7 +740,7 @@ paths: message: type: string example: Successfully updated members. - '401': + "401": description: Not logged in. content: application/json: @@ -805,7 +749,7 @@ paths: error: type: string example: Not logged in. - '403': + "403": description: User is not a SuperUser. content: application/json: @@ -837,7 +781,7 @@ paths: tags: - Organisation responses: - '200': + "200": description: OK content: application/json: @@ -846,7 +790,7 @@ paths: message: type: string example: Successfully deleted Admin. - '401': + "401": description: Not logged in. content: application/json: @@ -855,7 +799,7 @@ paths: error: type: string example: Not logged in. - '403': + "403": description: User is not a SuperUser. content: application/json: @@ -898,7 +842,7 @@ paths: type: string example: 2024-04-15T18:25:43.511Z responses: - '200': + "200": description: OK content: application/json: @@ -907,7 +851,7 @@ paths: message: type: string example: Successfully created campaign. - '403': + "403": description: User is not an admin of specified organisation. content: application/json: @@ -923,7 +867,7 @@ paths: tags: - Campaign responses: - '200': + "200": description: OK content: application/json: @@ -975,7 +919,7 @@ paths: tags: - Campaign responses: - '200': + "200": description: OK content: application/json: @@ -1039,7 +983,7 @@ paths: tags: - Campaign responses: - '200': + "200": description: OK content: application/json: @@ -1048,7 +992,7 @@ paths: message: type: string example: Successfully updated campaign. - '401': + "401": description: Not logged in. content: application/json: @@ -1057,7 +1001,7 @@ paths: error: type: string example: Not logged in. - '403': + "403": description: User is not an organisation admin. content: application/json: @@ -1080,7 +1024,7 @@ paths: tags: - Campaign responses: - '200': + "200": description: OK content: application/json: @@ -1089,7 +1033,7 @@ paths: message: type: string example: Successfully deleted campaign. - '403': + "403": description: User is not an admin of campaign's organisation. content: application/json: @@ -1113,7 +1057,7 @@ paths: tags: - Campaign responses: - '200': + "200": description: OK content: application/json: @@ -1123,7 +1067,7 @@ paths: type: string description: Presigned S3 url to upload file. example: https://www.youtube.com/watch?v=dQw4w9WgXcQ - '401': + "401": description: Not logged in. content: application/json: @@ -1132,7 +1076,7 @@ paths: error: type: string example: Not logged in. - '403': + "403": description: User is not an organisation admin. content: application/json: @@ -1180,7 +1124,7 @@ paths: description: Whether this role has been finalised (e.g. max avaliable number) example: False responses: - '200': + "200": description: OK content: application/json: @@ -1189,7 +1133,7 @@ paths: message: type: string example: Successfully created organisation. - '403': + "403": description: User is not a Campaign Admin. content: application/json: @@ -1214,7 +1158,7 @@ paths: tags: - Campaign responses: - '200': + "200": description: OK content: application/json: @@ -1223,8 +1167,8 @@ paths: campaigns: type: array items: - $ref: '#components/schemas/RoleDetails' - '401': + $ref: "#components/schemas/RoleDetails" + "401": description: Not logged in. content: application/json: @@ -1233,7 +1177,7 @@ paths: error: type: string example: Not logged in. - '403': + "403": description: User is not a Campaign Admin. content: application/json: @@ -1258,7 +1202,7 @@ paths: tags: - Campaign responses: - '200': + "200": description: OK content: application/json: @@ -1267,8 +1211,8 @@ paths: applications: type: array items: - $ref: '#components/schemas/ApplicationDetails' - '401': + $ref: "#components/schemas/ApplicationDetails" + "401": description: Not logged in. content: application/json: @@ -1277,7 +1221,7 @@ paths: error: type: string example: Not logged in. - '403': + "403": description: User is not a Campaign Admin. content: application/json: @@ -1287,7 +1231,6 @@ paths: type: string example: Unauthorized - /role/{id}: get: operationId: getRoleById @@ -1303,7 +1246,7 @@ paths: tags: - Role responses: - '200': + "200": description: OK content: application/json: @@ -1325,7 +1268,7 @@ paths: type: boolean description: Whether this role has been finalised (e.g. max avaliable number) example: False - '401': + "401": description: Not logged in. content: application/json: @@ -1372,7 +1315,7 @@ paths: description: Whether this role has been finalised (e.g. max avaliable number) example: true responses: - '200': + "200": description: OK content: application/json: @@ -1381,7 +1324,7 @@ paths: message: type: string example: Successfully update organisation. - '401': + "401": description: Not logged in. content: application/json: @@ -1390,7 +1333,7 @@ paths: error: type: string example: Not logged in. - '403': + "403": description: User is not a Campaign Admin. content: application/json: @@ -1414,7 +1357,7 @@ paths: tags: - Role responses: - '200': + "200": description: OK content: application/json: @@ -1423,7 +1366,7 @@ paths: message: type: string example: Successfully deleted role. - '401': + "401": description: Not logged in. content: application/json: @@ -1432,7 +1375,7 @@ paths: error: type: string example: Not logged in. - '403': + "403": description: User is not an admin of role's Campaign. content: application/json: @@ -1457,7 +1400,7 @@ paths: tags: - Role responses: - '200': + "200": description: OK content: application/json: @@ -1466,8 +1409,8 @@ paths: applications: type: array items: - $ref: '#components/schemas/ApplicationDetails' - '401': + $ref: "#components/schemas/ApplicationDetails" + "401": description: Not logged in. content: application/json: @@ -1476,7 +1419,7 @@ paths: error: type: string example: Not logged in. - '403': + "403": description: User is not an Application Admin. content: application/json: @@ -1501,7 +1444,7 @@ paths: tags: - Application responses: - '200': + "200": description: OK content: application/json: @@ -1509,8 +1452,8 @@ paths: properties: application: type: - $ref: '#components/schemas/ApplicationDetails' - '401': + $ref: "#components/schemas/ApplicationDetails" + "401": description: Not logged in. content: application/json: @@ -1519,7 +1462,7 @@ paths: error: type: string example: Not logged in. - '403': + "403": description: User is not an Application Admin. content: application/json: @@ -1529,7 +1472,6 @@ paths: type: string example: Unauthorized - /application/{id}/private: put: operationId: updateApplicationPrivateStatus @@ -1549,13 +1491,13 @@ paths: properties: data: type: - $ref: '#components/schemas/ApplicationStatus' + $ref: "#components/schemas/ApplicationStatus" description: Change Private Status of a specific Application tags: - Organisation responses: - '200': + "200": description: OK content: application/json: @@ -1564,7 +1506,7 @@ paths: message: type: string example: Successfully updated Application Private Status. - '401': + "401": description: Not logged in. content: application/json: @@ -1573,7 +1515,7 @@ paths: error: type: string example: Not logged in. - '403': + "403": description: User is not an Application Admin. content: application/json: @@ -1602,13 +1544,13 @@ paths: properties: data: type: - $ref: '#components/schemas/ApplicationStatus' + $ref: "#components/schemas/ApplicationStatus" description: Change Status of a specific Application tags: - Organisation responses: - '200': + "200": description: OK content: application/json: @@ -1617,7 +1559,7 @@ paths: message: type: string example: Successfully updated Application Status. - '401': + "401": description: Not logged in. content: application/json: @@ -1626,7 +1568,7 @@ paths: error: type: string example: Not logged in. - '403': + "403": description: User is not an Application Admin. content: application/json: @@ -1638,6 +1580,27 @@ paths: components: schemas: + NotLoggedIn: + type: object + properties: + message: + type: string + example: Not logged in + + Unauthorized: + type: object + properties: + message: + type: string + example: Unauthorized + + BadRequest: + type: object + properties: + message: + type: string + example: Bad request + Answer: type: object properties: @@ -1665,7 +1628,8 @@ components: example: 6996987893965227483 - type: array format: int64 - example: [6996987893965227483, 69969829832652228374, 6996987893965228374] + example: + [6996987893965227483, 69969829832652228374, 6996987893965228374] created_at: type: string example: 2024-03-15T18:25:43.511Z @@ -1696,9 +1660,8 @@ components: example: 6996987893965227483 - type: array format: int64 - example: [6996987893965227483, 69969829832652228374, 6996987893965228374] - - + example: + [6996987893965227483, 69969829832652228374, 6996987893965228374] ApplicationStatus: type: string @@ -1758,6 +1721,43 @@ components: description: Whether this role has been finalised (e.g. max avaliable number) example: False + User: + type: object + properties: + id: + type: integer + format: int64 + example: 1541815603606036480 + email: + type: string + example: me@example.com + zid: + type: string + example: z5555555 + nullable: true + name: + type: string + example: Clancy Lion + pronouns: + type: string + example: He/Him + gender: + type: string + example: Male + degree_name: + type: string + example: Computer Science + nullable: true + degree_starting_year: + type: integer + example: 2024 + nullable: true + role: + type: string + enum: + - User + - SuperUser + UserDetails: type: object properties: @@ -1799,15 +1799,15 @@ components: format: int64 example: 5141815603606036480 user: - $ref: '#/components/schemas/UserDetails' + $ref: "#/components/schemas/UserDetails" status: - $ref: '#/components/schemas/ApplicationStatus' + $ref: "#/components/schemas/ApplicationStatus" private_status: - $ref: '#/components/schemas/ApplicationStatus' + $ref: "#/components/schemas/ApplicationStatus" applied_roles: type: array items: - $ref: '#/components/schemas/ApplicationAppliedRoleDetails' + $ref: "#/components/schemas/ApplicationAppliedRoleDetails" ApplicationAppliedRoleDetails: type: object @@ -1818,4 +1818,8 @@ components: example: 1541815603606036480 role_name: type: String - example: UI/UX subcom \ No newline at end of file + example: Sponsorships + preference: + type: integer + format: int32 + example: 1