From 8ef0ccaf70b9c7f4b18d29bf2f52bbd711e858ee Mon Sep 17 00:00:00 2001 From: Kavika Date: Sat, 6 Apr 2024 13:24:13 +1100 Subject: [PATCH] Draft API Documentation for User, Organisation and Campaign (#478) * feat(docs): updates to user and organisation api spec * feat(docs): draft spec for campaign api * fix(ci): update rust workflow to use actions/cache --- .github/workflows/rust.yml | 18 +- backend/api.yaml | 405 ++++++++++++++++++++++++++++++++++++- 2 files changed, 414 insertions(+), 9 deletions(-) diff --git a/.github/workflows/rust.yml b/.github/workflows/rust.yml index fe8c05d7..59dc859e 100644 --- a/.github/workflows/rust.yml +++ b/.github/workflows/rust.yml @@ -3,6 +3,9 @@ name: Rust on: pull_request: branches: [main, "renovate/*", "CHAOS-224-KHAOS-rewrite"] + paths: + - backend/server/** + - backend/prisma-cli/** push: branches: ["renovate/*"] @@ -37,11 +40,18 @@ jobs: with: profile: minimal toolchain: stable - - uses: Swatinem/rust-cache@v2 + - name: Setup cargo cache + uses: actions/cache@v3 with: - workspaces: | - prisma-cli - server + path: | + ~/.cargo/bin/ + ~/.cargo/registry/index/ + ~/.cargo/registry/cache/ + ~/.cargo/git/db/ + backend/prisma-cli/target/ + backend/server/target/ + key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }} + restore-keys: ${{ runner.os }}-cargo- - name: Migrate DB working-directory: backend/prisma-cli run: cargo run db push diff --git a/backend/api.yaml b/backend/api.yaml index c6567fc9..cb80ef4f 100644 --- a/backend/api.yaml +++ b/backend/api.yaml @@ -9,6 +9,21 @@ servers: description: Local server paths: + /auth/logout: + post: + description: Invalidates current token. + tags: + - Auth + responses: + '200': + description: OK + content: + application/json: + schema: + properties: + messages: + type: string + example: Successfully logged out. /user: get: description: Returns info about currently logged in user. @@ -234,6 +249,44 @@ paths: error: type: string example: Not logged in. + /organisation: + post: + description: Creates a new organisation. + tags: + - Organisation + requestBody: + required: true + content: + application/json: + schema: + properties: + name: + type: string + example: "UNSW Software Development Society" + admin: + type: integer + format: int64 + example: 1541815603606036480 + description: User ID of admin + responses: + '200': + description: OK + content: + application/json: + schema: + properties: + message: + type: string + example: Successfully created organisation. + '403': + description: User is not a super user. + content: + application/json: + schema: + properties: + error: + type: string + example: Unauthorized /organisation/{id}: get: parameters: @@ -267,6 +320,37 @@ paths: created_at: type: string example: 2024-02-10T18:25:43.511Z + delete: + parameters: + - name: id + in: path + description: Organisation ID + required: true + schema: + type: integer + format: int64 + description: Deletes specified organisation. + tags: + - Organisation + responses: + '200': + description: OK + content: + application/json: + schema: + properties: + message: + type: string + example: Successfully deleted organisation. + '403': + description: User is not a super user. + content: + application/json: + schema: + properties: + error: + type: string + example: Unauthorized /organisation/{id}/campaigns: get: parameters: @@ -331,9 +415,10 @@ paths: application/json: schema: properties: - message: + upload_url: type: string - example: Successfully updated logo. + description: Presigned S3 url to upload file. + example: https://presignedurldemo.s3.eu-west-2.amazonaws.com/6996987893965262849/2d19617b-46fd-4927-9f53-77d69232ba5d?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAJJWZ7B6WCRGMKFGQ%2F20180210%2Feu-west-2%2Fs3%2Faws4_request&X-Amz-Date=20180210T171315Z&X-Amz-Expires=1800&X-Amz-Signature=12b74b0788aa036bc7c3d03b3f20c61f1f91cc9ad8873e3314255dc479a25351&X-Amz-SignedHeaders=host '401': description: Not logged in. content: @@ -351,8 +436,48 @@ paths: properties: error: type: string - example: Unauthorised. + example: Unauthorized /organisation/{id}/members: + get: + parameters: + - name: id + in: path + description: Organisation ID + required: true + schema: + type: integer + format: int64 + description: Returns list of members of specified organisation. + tags: + - Organisation + responses: + '200': + description: OK + content: + application/json: + schema: + properties: + members: + type: array + items: + type: object + properties: + id: + type: integer + format: int64 + example: 1541815603606036480 + name: + type: string + example: Clancy Lion + '403': + description: User is not an organisation admin or member. + content: + application/json: + schema: + properties: + error: + type: string + example: Unauthorized put: parameters: - name: id @@ -370,8 +495,8 @@ paths: properties: members: type: array + uniqueItems: true items: - uniqueItems: true type: integer format: int64 example: [1541815603606036480, 1541815603606036827, 1541815287306036429] @@ -405,4 +530,274 @@ paths: properties: error: type: string - example: Unauthorised. \ No newline at end of file + example: Unauthorized + /organisation/{id}/campaign: + post: + parameters: + - name: id + in: path + description: Organisation ID + required: true + schema: + type: integer + format: int64 + description: Creates a new campaign inside specified organisation. + tags: + - Organisation + requestBody: + required: true + content: + application/json: + schema: + properties: + name: + type: string + example: 2024 Subcommittee Recruitment + description: + type: string + example: Are you excited to make a difference? + starts_at: + type: string + example: 2024-03-15T18:25:43.511Z + ends_at: + type: string + example: 2024-04-15T18:25:43.511Z + responses: + '200': + description: OK + content: + application/json: + schema: + properties: + message: + type: string + example: Successfully created campaign. + '403': + description: User is not an admin of specified organisation. + content: + application/json: + schema: + properties: + error: + type: string + example: Unauthorized + /campaign: + get: + description: Returns all active campaigns. + tags: + - Campaign + responses: + '200': + description: OK + content: + application/json: + schema: + properties: + campaigns: + type: array + items: + type: object + properties: + id: + type: integer + format: int64 + example: 6996987893965262849 + organisation_id: + type: integer + format: int64 + example: 1541815603606036827 + organisation_name: + type: string + example: UNSW Software Development Society + name: + type: string + example: 2024 Subcommittee Recruitment + cover_image: + type: string + example: 2d19617b-46fd-4927-9f53-77d69232ba5d + description: + type: string + example: Are you excited to make a difference? + starts_at: + type: string + example: 2024-03-15T18:25:43.511Z + ends_at: + type: string + example: 2024-04-15T18:25:43.511Z + /campaign/{id}: + get: + parameters: + - name: id + in: path + description: Campaign ID + required: true + schema: + type: integer + format: int64 + description: Returns info about specified campaign. + tags: + - Campaign + responses: + '200': + description: OK + content: + application/json: + schema: + properties: + id: + type: integer + format: int64 + example: 6996987893965262849 + organisation_id: + type: integer + format: int64 + example: 1541815603606036827 + organisation_name: + type: string + example: UNSW Software Development Society + name: + type: string + example: 2024 Subcommittee Recruitment + cover_image: + type: string + example: 2d19617b-46fd-4927-9f53-77d69232ba5d + description: + type: string + example: Are you excited to make a difference? + starts_at: + type: string + example: 2024-03-15T18:25:43.511Z + ends_at: + type: string + example: 2024-04-15T18:25:43.511Z + put: + parameters: + - name: id + in: path + description: Campaign ID + required: true + schema: + type: integer + format: int64 + requestBody: + required: true + content: + application/json: + schema: + properties: + name: + type: string + example: 2024 Subcommittee Recruitment + description: + type: string + example: Are you excited to make a difference? + starts_at: + type: string + example: 2024-03-15T18:25:43.511Z + ends_at: + type: string + example: 2024-04-15T18:25:43.511Z + description: Updates details of specified campaign. + tags: + - Campaign + responses: + '200': + description: OK + content: + application/json: + schema: + properties: + message: + type: string + example: Successfully updated campaign. + '401': + description: Not logged in. + content: + application/json: + schema: + properties: + error: + type: string + example: Not logged in. + '403': + description: User is not an organisation admin. + content: + application/json: + schema: + properties: + error: + type: string + example: Unauthorized + delete: + parameters: + - name: id + in: path + description: Campaign ID + required: true + schema: + type: integer + format: int64 + description: Deletes specified campaign. + tags: + - Campaign + responses: + '200': + description: OK + content: + application/json: + schema: + properties: + message: + type: string + example: Successfully deleted campaign. + '403': + description: User is not an admin of campaign's organisation. + content: + application/json: + schema: + properties: + error: + type: string + example: Unauthorized + /campaign/{id}/banner: + patch: + parameters: + - name: id + in: path + description: Campaign ID + required: true + schema: + type: integer + format: int64 + description: Updates banner image for specified campaign. + tags: + - Campaign + responses: + '200': + description: OK + content: + application/json: + schema: + properties: + upload_url: + type: string + description: Presigned S3 url to upload file. + example: https://presignedurldemo.s3.eu-west-2.amazonaws.com/6996987893965262849/2d19617b-46fd-4927-9f53-77d69232ba5d?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAJJWZ7B6WCRGMKFGQ%2F20180210%2Feu-west-2%2Fs3%2Faws4_request&X-Amz-Date=20180210T171315Z&X-Amz-Expires=1800&X-Amz-Signature=12b74b0788aa036bc7c3d03b3f20c61f1f91cc9ad8873e3314255dc479a25351&X-Amz-SignedHeaders=host + '401': + description: Not logged in. + content: + application/json: + schema: + properties: + error: + type: string + example: Not logged in. + '403': + description: User is not an organisation admin. + content: + application/json: + schema: + properties: + error: + type: string + example: Unauthorized \ No newline at end of file