Skip to content

Service Contracts

Jump to bottom
Ashley-Kapaso edited this page Jun 26, 2024 · 1 revision

Database Schema

User Collection

Field Type Required Description
_id ObjectId True Unique identifier for the user
name String True User's first name
surname String True User's last name
username String True User's chosen username
email String True User's email address
password String True User's hashed password
image URL False URL or path to user's profile image
role String True User's role in the system
organisation ObjectId False Array of organisation IDs the user belongs to
workspaces List[ObjectId] False Array of workspace IDs the user has access to
createdAt Date True Timestamp of user creation
updatedAt Date True Timestamp of last user update

Organisation Collection

Field Type Required Description
_id ObjectId True Unique identifier for the organisation
name String True Organisation's name
image URL False URL or path to organisation's logo
createdBy ObjectId True ID of the user who created the organisation
createdAt Date True Timestamp of organisation creation
updatedAt Date True Timestamp of last organisation update

Workspace Collection

Field Type Required Description
_id ObjectId True Unique identifier for the workspace
name String True Workspace's name
image URL False URL or path to workspace's image
owner ObjectId True ID of the user who owns the workspace
organisation ObjectId True ID of the organisation the workspace belongs to
createdAt Date True Timestamp of workspace creation
updatedAt Date True Timestamp of last workspace update

Material Collection

Field Type Required Description
_id String True Unique identifier for the material
type String True Type of material (e.g., "3D model")
workspace_id ObjectId True ID of the workspace the material belongs to
lecturer_id ObjectId True ID of the lecturer who created the material
title String True Title of the material
description String False Description of the material
file_path URL True Path to the material file
createdAt Date True Timestamp of material creation
updatedAt Date True Timestamp of last material update

API Contract

Authentication

#

Endpoint: POST /#

  • Description: Register a new user account.
  • Request Body: 
    {
  "name": "John",
  "surname": "Doe",
  "email": "johndoe@example.com",
  "password": "password123",
  "role": "admin",
  "image": "https://example.com/images/johndoe.jpg"
}
  • Response: 
    {"messaage": "User created successfully"}

#

Endpoint: POST /signin

  • Description: Authenticate an existing user and return a token.
  • Request Body: 
    {
  "username": "a24125634",
  "password": "password123"
}
  • Response: 
    {
  "username": "a24125634",
  "name": "John",
  "surname": "Doe",
  "role": "admin",
  "organisations": ["60d21b4967d0d8992e610c86"],
  "workspaces": ["60d21b4c67d0d8992e610c87"],
  "image": "https://example.com/images/johndoe.jpg",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9"
}

User Management

Create User

Endpoint: POST /users

  • Description: Create a new user. The username will be generated by the server.

  • Request Body:

    {
  "name": "John",
  "surname": "Doe",
  "email": "johndoe@example.com",
  "password": "password123",
  "role": "admin",
  "image": "https://example.com/images/johndoe.jpg"
}

  • Response:

    {
  "id": "60d21b4667d0d8992e610c85",
  "username": "a24125634",
  "name": "John",
  "surname": "Doe",
  "email": "johndoe@example.com",
  "role": "admin",
  "organisations": ["60d21b4967d0d8992e610c86"],
  "workspaces": [],
  "image": "https://example.com/images/johndoe.jpg",
  "createdAt": "2023-01-01T00:00:00.000Z",
  "updatedAt": "2023-01-01T00:00:00.000Z"
}

Get User

Endpoint: GET /users/{id}

  • Description: Retrieve a user's details.
  • Response: 
    {
  "id": "60d21b4667d0d8992e610c85",
  "username": "a24125634",
  "name": "John",
  "surname": "Doe",
  "email": "johndoe@example.com",
  "role": "admin",
  "organisations": ["60d21b4967d0d8992e610c86"],
  "workspaces": ["60d21b4c67d0d8992e610c87"],
  "image": "https://example.com/images/johndoe.jpg",
  "createdAt": "2023-01-01T00:00:00.000Z",
  "updatedAt": "2023-01-01T00:00:00.000Z"
}

Get Users

Endpoint: GET /users?organisation=orgid

  • Description: Retrieve a list users details depending on the filter
  • Response: 
    [
  {
    "id": "60d21b4667d0d8992e610c85",
    "username": "a24125634",
    "name": "John",
    "surname": "Doe",
    "email": "johndoe@example.com",
    "role": "admin",
    "organisations": ["60d21b4967d0d8992e610c86"],
    "workspaces": ["60d21b4c67d0d8992e610c87"],
    "image": "https://example.com/images/johndoe.jpg",
    "createdAt": "2023-01-01T00:00:00.000Z",
    "updatedAt": "2023-01-01T00:00:00.000Z"
  },
  {
   "id": "60d21b4667d0d8992e610c85",
   "username": "s24124534",
   "name": "Sam",
   "surname": "Dude",
   "email": "johndoe@example.com",
   "role": "admin",
   "organisations": ["60d21b4967d0d8992e610c86"],
   "workspaces": ["60d21b4c67d0d8992e610c87"],
   "image": "https://example.com/images/johndoe.jpg",
   "createdAt": "2023-01-01T00:00:00.000Z",
   "updatedAt": "2023-01-01T00:00:00.000Z"
  }
]

Update User

Endpoint: PUT /users/{id}

  • Description: Update a user's details.
  • Request Body: 
    {
  "name": "Jonathan",
  "surname": "Doe",
  "email": "john_doe@example.com",
  "role": "lecturer",
  "image": "https://example.com/images/jonathandoe.jpg"
}
  • Response: 
    {
  "id": "60d21b4667d0d8992e610c85",
  "username": "a24125634",
  "name": "Jonathan",
  "surname": "Doe",
  "email": "john_doe@example.com",
  "role": "lecturer",
  "organisations": ["60d21b4967d0d8992e610c86"],
  "workspaces": ["60d21b4c67d0d8992e610c87"],
  "image": "https://example.com/images/jonathandoe.jpg",
  "createdAt": "2023-01-01T00:00:00.000Z",
  "updatedAt": "2023-01-02T00:00:00.000Z"
}

Delete User

Endpoint: DELETE /users/{id}

  • Description: Delete a user.
  • Response: 
    {
  "message": "User deleted successfully."
}

Organisation Management

Create Organisation

Endpoint: POST /organisations

  • Description: Create a new organisation.
  • Request Body: 
    {
  "name": "University of Example",
  "createdBy": "60d21b4667d0d8992e610c85",
  "image": "https://example.com/images/university.jpg"
}
  • Response: 
    {
  "id": "60d21b4967d0d8992e610c86",
  "name": "University of Example",
  "createdBy": "60d21b4667d0d8992e610c85",
  "users": ["60d21b4667d0d8992e610c85"],
  "image": "https://example.com/images/university.jpg",
  "createdAt": "2023-01-01T00:00:00.000Z",
  "updatedAt": "2023-01-01T00:00:00.000Z"
}

Get Organisation

Endpoint:

GET /organisations/{id}

  • Description: Retrieve an organisation's details.
  • Response: 
    {
  "id": "60d21b4967d0d8992e610c86",
  "name": "University of Example",
  "createdBy": "60d21b4667d0d8992e610c85",
  "users": ["60d21b4667d0d8992e610c85"],
  "image": "https://example.com/images/university.jpg",
  "createdAt": "2023-01-01T00:00:00.000Z",
  "updatedAt": "2023-01-01T00:00:00.000Z"
}

Update Organisation

Endpoint: PUT /organisations/{id}

  • Description: Update an organisation's details.
  • Request Body: 
    {
  "name": "University of Example - Updated",
  "image": "https://example.com/images/university_updated.jpg"
}
  • Response: 
    {
  "id": "60d21b4967d0d8992e610c86",
  "name": "University of Example - Updated",
  "createdBy": "60d21b4667d0d8992e610c85",
  "users": ["60d21b4667d0d8992e610c85"],
  "image": "https://example.com/images/university_updated.jpg",
  "createdAt": "2023-01-01T00:00:00.000Z",
  "updatedAt": "2023-01-02T00:00:00.000Z"
}

Delete Organisation

Endpoint: DELETE /organisations/{id}

  • Description: Delete an organisation.
  • Response: 
    {
  "message": "Organisation deleted successfully."
}

Workspace Management

Create Workspace

Endpoint: POST /workspaces

  • Description: Create a new workspace.
  • Request Body: 
    {
  "name": "Development",
  "organisationId": "60d21b4967d0d8992e610c86",
  "createdBy": "60d21b4667d0d8992e610c85",
  "image": "https://example.com/images/development.jpg"
}
  • Response: 
    {
  "id": "60d21b4c67d0d8992e610c87",
  "name": "Development",
  "organisationId": "60d21b4967d0d8992e610c86",
  "createdBy": "60d21b4667d0d8992e610c85",
  "users": ["60d21b4667d0d8992e610c85"],
  "image": "https://example.com/images/development.jpg",
  "createdAt": "2023-01-01T00:00:00.000Z",
  "updatedAt": "2023-01-01T00:00:00.000Z"
}

Get Workspace

Endpoint: GET /workspaces/{id}

  • Description: Retrieve a workspace's details.
  • Response: 
    {
  "id": "60d21b4c67d0d8992e610c87",
  "name": "Development",
  "organisationId": "60d21b49667d0d8992e610c86",
  "createdBy": "60d21b4667d0d8992e610c85",
  "users": ["60d21b4667d0d8992e610c85"],
  "image": "https://example.com/images/development.jpg",
  "createdAt": "2023-01-01T00:00:00.000Z",
  "updatedAt": "2023-01-01T00:00:00.000Z"
}

Get Workspaces

Endpoint: GET /workspaces?organisation=orgid

  • Description: Retrieve a list workspaces details depending on the filter
  • Response:
[
  {
    "id": "60d21b4c67d0d8992e610c87",
    "name": "Development",
    "organisationId": "60d21b49667d0d8992e610c86",
    "createdBy": "60d21b4667d0d8992e610c85",
    "users": ["60d21b4667d0d8992e610c85"],
    "image": "https://example.com/images/development.jpg",
    "createdAt": "2023-01-01T00:00:00.000Z",
    "updatedAt": "2023-01-01T00:00:00.000Z"
  },
  {
    "id": "60d21b4c67d0d8992a610c87",
    "name": "Science",
    "organisationId": "60d21b49667d0d8992e610c86",
    "createdBy": "60d21b4667d0d8992e610c85",
    "users": ["60d21b4667d0d8992e610c85"],
    "image": "https://example.com/images/development.jpg",
    "createdAt": "2023-01-01T00:00:00.000Z",
    "updatedAt": "2023-01-01T00:00:00.000Z"
  }
]

Update Workspace

Endpoint: PUT /workspaces/{id}

  • Description: Update a workspace's details.
  • Request Body: 
    {
  "name": "Advanced Development",
  "image": "https://example.com/images/advanced_development.jpg"
}
  • Response: 
    {
  "id": "60d21b4c67d0d8992e610c87",
  "name": "Advanced Development",
  "organisationId": "60d21b4967d0d8992e610c86",
  "createdBy": "60d21b4667d0d8992e610c85",
  "users": ["60d21b4667d0d8992e610c85"],
  "image": "https://example.com/images/advanced_development.jpg",
  "createdAt": "2023-01-01T00:00:00.000Z",
  "updatedAt": "2023-01-02T00:00:00.000Z"
}

Delete Workspace

Endpoint: DELETE /workspaces/{id}

  • Description: Delete a workspace.
  • Response: 
    {
  "message": "Workspace deleted successfully."
}

Material Management

1. Create Material

  • Endpoint: /materials
  • Method: POST
  • Description: Creates a new material in the collection.
  • Request Body: 
    {
    "type": "3D model",
    "workspace_id": "string",
    "lecturer_id": "string",
    "title": "string",
    "description": "string",
    "file_path": "string"
}
  • Response: 
    {
    "_id": "string",
    "type": "3D model",
    "workspace_id": "string",
    "lecturer_id": "string",
    "title": "string",
    "description": "string",
    "file_path": "string",
    "created_at": "datetime",
    "updated_at": "datetime"
}

2. Get Material by ID

  • Endpoint: /materials/{id}
  • Method: GET
  • Description: Retrieves a material by its ID.
  • Request Parameters:
    • id: string (path parameter)
  • Response: 
    {
    "_id": "string",
    "type": "3D model",
    "workspace_id": "string",
    "lecturer_id": "string",
    "title": "string",
    "description": "string",
    "file_path": "string",
    "created_at": "datetime",
    "updated_at": "datetime"
}

3. Update Material

  • Endpoint: /materials/{id}
  • Method: PUT
  • Description: Updates an existing material.
  • Request Parameters:
    • id: string (path parameter)
  • Request Body: 
    {
    "type": "3D model",
    "workspace_id": "string",
    "lecturer_id": "string",
    "title": "string",
    "description": "string",
    "file_path": "string"
}
  • Response: 
    {
    "_id": "string",
    "type": "3D model",
    "workspace_id": "string",
    "lecturer_id": "string",
    "title": "string",
    "description": "string",
    "file_path": "string",
    "created_at": "datetime",
    "updated_at": "datetime"
}

4. Delete Material

  • Endpoint: /materials/{id}
  • Method: DELETE
  • Description: Deletes a material by its ID.
  • Request Parameters:
    • id: string (path parameter)
  • Response: 
    {
  "message": "Learning Material deleted successfully"
}

5. List All Materials

  • Endpoint: /materials
  • Method: GET
  • Description: Retrieves a list of all materials.
  • Response: 
    [
    {
        "_id": "string",
        "type": "3D model",
        "workspace_id": "string",
        "lecturer_id": "string",
        "title": "string",
        "description": "string",
        "file_path": "string",
        "created_at": "datetime",
        "updated_at": "datetime"
    }
]
© Phantom Works

primary logo

Clone this wiki locally