API v1

[YoungerMax]

Objects

Date

All dates are UTC ISO 8601 dates

Example: 2023-06-19T01:17:05.565Z

IDs

All IDs are UUID 4

Example: 90da6511-685e-4538-a2cf-19c112616c8f

User

Example:

{
    "id": "90da6511-685e-4538-a2cf-19c112616c8f",
    "email": "example@example.com",
    "lastSignedIn": "2023-06-19T01:17:05.565Z",
    "joinedOn": "2023-06-19T01:17:05.565Z",
    "history": [
        {
            "type": "studentTypeSurveyResponse",
            "timestamp": "2023-06-19T01:17:05.565Z",
            "data": {
                "responded": "college"
            }
        }
    ]
}

history explanation

• Used to store data that only some users have
• For example, if a user responded to a survey that we gave them asking what kind of student they are (high school, college, other), the studentTypeSurveyResponse would store what they responded with
• TODO: need a better, more descriptive name

Note

{
    "id": "4f91ef86-70ae-42ef-b156-81566bd4230b",
    "type": "note",
    "metadata": {
        "name": "3.5.2 Example name",
        "path": ["3. Computers", "3.5 folder inside a folder"],
        "lastEdited": "2023-06-19T01:17:05.565Z",
        "createdOn": "2023-06-19T01:17:05.565Z",
        "owner": {
            "id": "90da6511-685e-4538-a2cf-19c112616c8f",
            "email": "example@example.com",
            "lastSignedIn": "2023-06-19T01:17:05.565Z",
            "joinedOn": "2023-06-19T01:17:05.565Z",
            "history": [
                {
                    "type": "studentTypeSurveyResponse",
                    "timestamp": "2023-06-19T01:17:05.565Z",
                    "data": {
                        "responded": "college"
                    }
                }
            ]
        }
    },
    "blocks": [
        {
            "type": "text",
            "data": {
                "content": "<serialized data>"
            }
        },
        {
            "type": "image",
            "data": {
                "url": "<serialized URL data>"
            }
        }
    ]
}

• metadata.path is the parent folder path to the note. It is an array so that any characters can go in the folder names. This solves the problem of not being able to put / in folder or file names and may fix potential bugs.
  • if you were to translate this into a file path, it would be 3. Computers / 3.5 folder inside a folder / 3.5.2 Example name where 3.5.2 Example name is the file, and 3. Computers and 3.5 folder inside a folder are parent folders

Folder

{
    "id": "4f91ef86-70ae-42ef-b156-81566bd4230b",
    "type": "folder",
    "metadata": {
        "name": "3. Computers",
        "path": [],
        "lastEdited": "2023-06-19T01:17:05.565Z",
        "createdOn": "2023-06-19T01:17:05.565Z",
        "owner": {
            "id": "90da6511-685e-4538-a2cf-19c112616c8f",
            "email": "example@example.com",
            "lastSignedIn": "2023-06-19T01:17:05.565Z",
            "joinedOn": "2023-06-19T01:17:05.565Z",
            "history": [
                {
                    "type": "studentTypeSurveyResponse",
                    "timestamp": "2023-06-19T01:17:05.565Z",
                    "data": {
                        "responded": "college"
                    }
                }
            ]
        }
    }
}

Authentication

• Use a cookie called authenticate which contains a secure random string (token)
• Match the contents of authenticate against a database to get user

Endpoints

GET /

Authentication accepted, but not required No request body accepted at all. Return 400 Bad Request if a body is given.

Description

Get server status, server information, user information

Return

• If not authenticated: 200 OK, body:

  {
  "apiVersion": 1,
  "user": null
  }

• If authenticated: 200 OK, body:

  {
  "apiVersion": 1,
  "user": {
      "id": "90da6511-685e-4538-a2cf-19c112616c8f",
      "email": "example@example.com",
      "lastSignedIn": "2023-06-19T01:17:05.565Z",
      "joinedOn": "2023-06-19T01:17:05.565Z",
      "history": [
          {
              "type": "studentTypeSurveyResponse",
              "timestamp": "2023-06-19T01:17:05.565Z",
              "data": {
                  "responded": "college"
              }
          }
      ]
  }
  }

• If server error: 500 Internal Server Error, no body

POST /items/list

Must be authenticated.

Description

Because the notes/folders are being implemented by a file system, this endpoint lists notes in a path

Request Body

• JSON serialized string array of parent folder names
• Example:

  ["3. Computers", "3.5 folder inside a folder"]

Return

• Success: 200 OK, body: a JSON array of Note that belong to the authenticated user and are inside the path given in the request body.
• Folder/file doesn't exist: 400 Bad Request, no body
• If server error: 500 Internal Server Error, no body

DELETE /items/delete

Must be authenticated. Deny request bodies with 400 Bad Request.

Description

Delete resources (notes or folders) by ID

Query Params

• id
  • Example: 4f91ef86-70ae-42ef-b156-81566bd4230b, an ID of a note

Return

• On success: 204 No Content, no body
• If note doesn't exist: 400 Bad Request, no body
• If server error: 500 Internal Server Error, no body
• If not authenticated: 401 Unauthorized, no body

POST /items/create/note

Must be authenticated.

Description

This endpoint creates a note and returns the created note

Request Body

• JSON object
• Example:

  {
  "name": "Note name here",
  "path": []
  }

• Empty path array means root directory

Return

• Success: 201 Created, body is the Note that was created
• If path does not exist: 400 Bad Request, no body
• If server error: 500 Internal Server Error, no body
• If not authenticated: 401 Unauthorized, no body

POST /items/create/studyguide

Must be authenticated.

Description

This endpoint creates a study guide and returns it. Important: study guides are notes, just auto-generated on the server.

Request Body

• JSON object
• Example:

  {
  "name": "Study guide name here",
  "path": ["Unit 1: Macromolecules"]
  }

Return

• Success: 201 Created, body is the Note that was created (but is really a study guide)
• If path does not exist: 400 Bad Request, no body
• If server error: 500 Internal Server Error, no body
• If not authenticated: 401 Unauthorized, no body

POST /items/create/folder

Must be authenticated.

Description

This endpoint creates a folder and returns the created folder

Request Body

• JSON object
• Example:

  {
  "name": "NewFolderInParents",
  "path": ["ParentFolder1", "ParentFolder2"]
  }

Return

• Success: 201 Created, body is the Folder that was created
• If path does not exist: 400 Bad Request, no body
• If server error: 500 Internal Server Error, no body
• If not authenticated: 401 Unauthorized, no body

POST /items/update/metadata

Must be authenticated.

Description

Update a resource's (folder/note) metadata (path/name) by ID

Query Params

• id: string that corresponds to ID of resource (note or folder)
  • Example: POST /items/update/metadata?id=4f91ef86-70ae-42ef-b156-81566bd4230b: update resource with id of 4f91ef86-70ae-42ef-b156-81566bd4230b

Request Body

• JSON object

• Example:

  {
  "name": "New Folder Name",
  "path": []
  }

  • Move resource (folder or note) with id of 4f91ef86-70ae-42ef-b156-81566bd4230b to the root and change name to New Folder Name
• Update lastEdited of this folder on the server!

Return

• Success: 204 No Content, no body
• If id does not exist: 400 Bad Request, no body
• If server error: 500 Internal Server Error, no body
• If not authenticated: 401 Unauthorized, no body

PUT /items/update/blocks

Must be authenticated.

Description

Update the contents (blocks) in a note by its ID

Query Params

• id: string that corresponds to ID of note only
  • Example: PUT /items/update/blocks?id=4f91ef86-70ae-42ef-b156-81566bd4230b: update note blocks with id of 4f91ef86-70ae-42ef-b156-81566bd4230b

Request Body

• JSON array of block objects
• Example:

  [
  {
      "type": "text",
      "data": {
          "content": "<serialized data>"
      }
  },
  {
      "type": "image",
      "data": {
          "url": "<serialized URL data>"
      }
  }
  ]

Return

• Success: 204 No Content, no body
• If id does not exist: 400 Bad Request, no body
• If server error: 500 Internal Server Error, no body
• If not authenticated: 401 Unauthorized, no body

[YoungerMax]

In v2, make note saving incremental

[aodhfionn]

We should use a shorter hash instead of a full-length UUID 4. We could truncate the length of the UUID 4 to about 6-8 characters.

The possibility of hash collision can be avoided by implementing a fail-safe that checks if the newly truncated id matches an id that already exists, and then just re-generate it.