Skip to content

Latest commit

 

History

History
702 lines (600 loc) · 10.9 KB

DOCUMENTS.MD

File metadata and controls

702 lines (600 loc) · 10.9 KB

OBCS API Documentation

Table of Contents

Authentication and Authorization

User Registration

POST /api/auth/signup
Content-Type: application/json

Request Body:

{
    "Username": "string", // Required, unique
    "Password": "string", // Required
    "UserType": "string" // Required, values: "user" or "admin"
}

Response:

{
    "Token": "string"
}

Status Codes:

  • 200: Registration successful
  • 400: Invalid request parameters
  • 409: Username already exists
  • 403: Attempt to create root user

User Login

POST /api/auth/signin
Content-Type: application/json

Request Body:

{
    "Username": "string", // Required
    "Password": "string" // Required
}

Response: Same as registration endpoint

Status Codes:

  • 200: Login successful
  • 401: Invalid username or password

Delete Account

POST /api/auth/delete
Authorization: Bearer <token>
Content-Type: application/json

Request Body:

{
    "Username": "string" // Required
}

Status Codes:

  • 200: Deletion successful
  • 401: Token invalid or mismatched
  • 403: Cannot delete root account

User Logout

POST /api/auth/logout
Authorization: Bearer <token>

Status Codes:

  • 200: Logout successful
  • 401: Token invalid

Profile Management

Retrieve Public Profile

GET /api/profile/{username}

Response: ProfileDto object

Status Codes:

  • 200: Success
  • 404: User does not exist

Update Profile

PUT /api/profile/{username}
Authorization: Bearer <token>
Content-Type: application/json

Request Body: ProfileDto object

Response:

{
    "success": true
}

Status Codes:

  • 200: Success
  • 401: Token invalid or mismatched
  • 404: User does not exist

Retrieve Private Profile

GET /api/profile/me
Authorization: Bearer <token>

Response: ProfileDto object

Status Codes:

  • 200: Success
  • 401: Token invalid
  • 404: Profile does not exist

Admin Operations

Check Admin Permission

GET /api/admin/permission
Authorization: Bearer <token>

Response:

{
    "success": true,
    "type": "string" // "admin" or "root"
}

Status Codes:

  • 200: Success
  • 401: Token invalid
  • 403: Insufficient permission

Retrieve User List

GET /api/admin/users
Authorization: Bearer <token>

Response:

{
    "Users": [
        {
            "Username": "string",
            "Type": "string"
        }
    ]
}

Status Codes:

  • 200: Success
  • 401: Token invalid
  • 403: Insufficient permission

Create User (Admin)

POST /api/admin/users
Authorization: Bearer <token>
Content-Type: application/json

Request Body:

{
    "NewUsername": "string", // Required
    "Password": "string", // Required
    "Type": "string" // Required, values: "user" or "admin"
}

Response:

{
    "Token": "string"
}

Status Codes:

  • 200: Success
  • 400: Invalid request parameters
  • 401: Token invalid
  • 403: Insufficient permission
  • 409: Username already exists

Delete User (Admin)

DELETE /api/admin/users/{username}
Authorization: Bearer <token>

Status Codes:

  • 200: Success
  • 400: Cannot delete own account
  • 401: Token invalid
  • 403: Insufficient permission or cannot delete root account
  • 404: User does not exist

Classic API (lower camelCase)

Classic User Registration

POST /classic/signup/create
Content-Type: application/json

Request Body:

{
    "userName": "string", // Required, unique
    "password": "string", // Required
    "type": "string" // Required, values: "user" or "admin"
}

Response:

{
    "token": "string"
}

Classic User Login

POST /classic/signin
Content-Type: application/json

Request Body:

{
    "userName": "string", // Required
    "password": "string" // Required
}

Response: Same as registration endpoint

Classic Delete Account

POST /classic/delete
Content-Type: application/json

Request Body:

{
    "userName": "string", // Required
    "token": "string" // Required
}

Response:

{
    "message": "string"
}

Classic Retrieve User Profile

GET /classic/user/{username}

Response: ClassicProfile object

Classic Update User Profile

POST /classic/user/{username}
Authorization: Bearer <token>
Content-Type: application/json

Request Body: ClassicProfile object

Response:

{
    "success": true
}

Classic Check Admin Permission

POST /classic/admin/check-permission
Content-Type: application/json

Request Body:

{
    "userName": "string", // Required
    "token": "string" // Required
}

Response:

{
    "success": true,
    "type": "string" // "admin" or "root"
}

Classic Retrieve User List

GET /classic/admin/users

Note: Token and username must be passed in Header or Body

Classic Create User (Admin)

POST /classic/admin/users
Content-Type: application/json

Request Body:

{
    "userName": "string", // Admin username
    "token": "string", // Admin token
    "newUserName": "string", // New username
    "password": "string", // New user password
    "type": "string" // New user type, values: "user" or "admin"
}

Response:

{
    "message": "string",
    "token": "string" // Token for new user
}

Classic Delete User (Admin)

DELETE /classic/admin/users/{targetUsername}
Content-Type: application/json

Request Body:

{
    "userName": "string", // Admin username
    "token": "string" // Admin token
}

Response:

{
    "message": "string"
}

Classic Initialize Admin

GET /classic/init-admin

Response: String "Admin initialized" or "Admin already initialized"

Data Structures

SignUpRequest

{
    "Username": "string",
    "Password": "string",
    "UserType": "string"
}

SignInRequest

{
    "Username": "string",
    "Password": "string"
}

DeleteRequest

{
    "Username": "string"
}

TokenResponse

{
    "Token": "string"
}

ProfileDto

{
    "Username": "string",
    "Avatar": AssetDto,
    "NickName": "string",
    "Pronouns": "string",
    "Description": "string",
    "Location": "string",
    "Website": "string",
    "Background": AssetDto,
    "CurrentCompany": "string",
    "CurrentCompanyLink": "string",
    "CurrentSchool": "string",
    "CurrentSchoolLink": "string",
    "Contacts": [ContactItemDto],
    "SocialLinks": [SocialLinkItemDto],
    "Projects": [ProjectItemDto],
    "WorkExperiences": [WorkExperienceItemDto],
    "SchoolExperiences": [SchoolExperienceItemDto],
    "Gallery": [GalleryItemDto]
}

AssetDto

{
    "Type": "string", // "Text", "Image", "Remote", "Style"
    "Text": "string",
    "DataBase64": "string"
}

ContactItemDto

{
    "Type": "string",
    "Text": "string",
    "Image": AssetDto
}

SocialLinkItemDto

{
    "Type": "string",
    "Value": "string",
    "Attributes": {
        "key": "value"
    }
}

ProjectItemDto

{
    "Name": "string",
    "Url": "string",
    "Description": "string",
    "Logo": AssetDto
}

WorkExperienceItemDto

{
    "Company": "string",
    "CompanyUrl": "string",
    "Position": "string",
    "StartDate": "string", // yyyy-MM-dd
    "EndDate": "string", // yyyy-MM-dd
    "Description": "string",
    "Logo": AssetDto
}

SchoolExperienceItemDto

{
    "School": "string",
    "SchoolLink": "string",
    "Degree": "string",
    "Major": "string",
    "StartDate": "string", // yyyy-MM-dd
    "EndDate": "string", // yyyy-MM-dd
    "Description": "string",
    "Logo": AssetDto
}

GalleryItemDto

{
    "Image": AssetDto,
    "Caption": "string"
}

CreateUserRequest

{
    "NewUsername": "string",
    "Password": "string",
    "Type": "string"
}

UserInfoDto

{
    "Username": "string",
    "Type": "string"
}

UserListResponse

{
    "Users": [UserInfoDto]
}

Classic Compatibility Data Structures (lower camelCase)

ClassicSignUpRequest

{
    "userName": "string",
    "password": "string",
    "type": "string"
}

ClassicSignInRequest

{
    "userName": "string",
    "password": "string"
}

ClassicDeleteRequest

{
    "userName": "string",
    "token": "string"
}

ClassicTokenResponse

{
    "token": "string"
}

ClassicProfile

{
    "username": "string",
    "name": "string",
    "pronouns": "string",
    "avatar": "string", // Base64 Data URI / URL / Text
    "bio": "string",
    "location": "string",
    "website": "string",
    "background": "string", // Base64 Data URI / URL / Text
    "currentCompany": "string",
    "currentCompanyLink": "string",
    "currentSchool": "string",
    "currentSchoolLink": "string",
    "contacts": [ClassicContact],
    "socialLinks": [ClassicSocialLink],
    "projects": [ClassicProject],
    "workExperiences": [ClassicWorkExperience],
    "schoolExperiences": [ClassicSchoolExperience],
    "gallery": [ClassicGalleryItem]
}

ClassicContact

{
    "type": "string",
    "value": "string" // Text or Base64 Data URI
}

ClassicSocialLink

{
    "type": "string",
    "value": "string",
    "githubData": {
        // Arbitrary key-value pairs
    }
}

ClassicProject

{
    "name": "string",
    "url": "string",
    "description": "string",
    "logo": "string" // Base64 Data URI / URL
}

ClassicWorkExperience

{
    "position": "string",
    "company": "string",
    "companyLink": "string",
    "startDate": "string", // yyyy-MM-dd
    "endDate": "string", // yyyy-MM-dd
    "description": "string",
    "logo": "string" // Base64 Data URI / URL
}

ClassicSchoolExperience

{
    "school": "string",
    "schoolLink": "string",
    "degree": "string",
    "major": "string",
    "startDate": "string", // yyyy-MM-dd
    "endDate": "string", // yyyy-MM-dd
    "description": "string",
    "logo": "string" // Base64 Data URI / URL
}

ClassicGalleryItem

{
    "image": "string", // Base64 Data URI
    "caption": "string"
}

ClassicAdminRequest

{
    "userName": "string",
    "token": "string"
}

ClassicCreateUserRequest

{
    "userName": "string",
    "token": "string",
    "newUserName": "string",
    "password": "string",
    "type": "string"
}

ClassicUserInfo

{
    "userName": "string",
    "type": "string"
}

ClassicUserListResponse

{
  "users": [ClassicUserInfo]
}