Skip to content

API description

Jump to bottom
Mathéo Morin edited this page Feb 27, 2025 · 22 revisions

Important information for Deadline 1

‼️  This chapter should be completed by Deadline 1 (see course information at Lovelace)

📑  Chapter summary This chapter must provide a good overview of the Web API that your group is going to develop during the course, and some insight into the (imaginary) microservice architecture it will be a part of. You should not focus in implementation aspects such as database structure, interfaces or the request/responses formats. We recommend that you look into existing APIs (see Related work below) before writing the description for your own API.

Chapter GOALS:

  1. Understand what is an API
  2. Describe the project topic API
  3. Describe how the API would be used as part of a larger architecture
✔️     Chapter evaluation (max 5 points) You can get a maximum of 5 points after completing this Chapter. More detailed evaluation is provided in the evaluation sheet in Lovelace.

RESTful API description

Overview

📑  Content that must be included in the section

Describe the API you are going to implement. Also describe the larger imaginary architecture that would exist around that API - while you do not need to implement these other components, they will be helpful in imagining context for your API. Your API will be a component that stores, and offers an interface to, some important data in the larger ecosystem. Think about a larger system, and then take out one key piece to examine - this will be your API.

Describe the API briefly and comment what is the main functionality that it exposes. Focus in the API not in any specific application that is using this API. Take into account that in the end, a WEB API is an encapsulated functionality as well as the interface to access that functionality. Remember that your API is just one part of a larger machine. It does not need to do everything. There will be other components in the system to do those things. This course focuses on creating a small API in detail - thinking too big from the start will drown you in work later.

A really short version of an overview for the RESTful Web API could be:

“The discussion forum Web API offers different functionalities to structure non-real-time conversations among the people of a group about topics they are interested in certain topic. Messages are grouped in Threads, that at the same time are grouped in Topics. The messages are accessible to anyone, but posts can only be created by providing credentials of a registered user [...] This API could exist as part of an online learning environment system where it is responsible for offering discussion forum features that can be included in other components of the learning environment. For example, a programming task (managed by a different component) can include its own discussion board managed by the discussion forum API[...]“

Introduction to the API

The Task Management Web API is designed to facilitate the creation, organization, and management of tasks in different projects. It serves as a key component in a larger productivity ecosystem (clickup, notion, jira etc.), enabling users and teams to collaborate effectively, track progress, and meet deadlines. In addition to standard task management features, this API offers an advanced endpoint powered by a large language model (LLM) that takes in all the information about the project and then breaks the project down into executable tasks. This API can be used by different organizations when they are collaborating with each other and are using completely differnt systems and environments, this API can be used to bridge the two collaborating organizations by keep all of their joint projects, tasks, users in the form of an API which can be consumed by each of the organizations in their own way natively in their ecosystem. For example if one organization uses Clickup for project management and the other organization uses Jira, they can both stay on their ecosystem and use this API to keep the work in sync, and the LLM endpoint can be very useful when first migrating to the API or starting a new project, it will automatically break it down for you.

Core Functionalities

Task Management:

Create, edit, and delete tasks. Assign tasks to users or teams. Set deadlines, priorities, and categories for tasks. Mark tasks as complete or in-progress.

Project Management:

Group related tasks into projects. Track the overall progress of projects. Task Collaboration:

Task Breakdown Using LLM:

Input a high-level project description. Use an LLM-powered agent to analyze the project and generate a list of smaller, actionable tasks. Output includes task details like estimated time, priority, and dependencies.

Technologies Used

Flask: A minimal yet powerful Python web framework for building scalable APIs, offering built-in routing and middleware support.

React.js: React is a really famous framework for build responsive web applications and would be a good choice to built the frontend. Along with TailwindCSS which is a popular styling library.

MongoDB: A NoSQL database suited for managing unstructured and hierarchical data like tasks and projects.

Notebook LM: We will use NotebookLM as a headless server application to provide the API for the LLM which our backend will consume to break down the project. The Notebook LM will use DeepSeek-R1-Distill-Qwen-7B-GGUF which is a small model with 7B parameters.

WebSockets: Enable real-time task updates and push notifications.

Main concepts and relations

📑  Content that must be included in the section Define the main concepts and describe the relations among them textually. Roughly, a concept is a real-world entity that is expected to be of interest to users or other services. This section will be a guideline for choosing your resources to implement in Deadline 3. Students should remember that some of the concepts might not be a resource by themselves, but just a part of it (resource property). In this section, students should not describe the RESTful resources, but identify which are the main ideas of the API. Do not forget to include the relations among the concepts.

A description of the main concepts for the Forum API could be:

"The API permits users send messages. The forum contains a list of categories and a list of users. Each category specifies a name, a description and a thread. A thread is [...]The forum may contain 0 or more categories… Each category may have 0 or more threads… Users can write and read messages to a forum thread. A user has a profile, basic information, activity information (stores, for instance, all the messages sent by a user, the messages marked as favorites). [...]The user history contains information of the last 30 messages sent by the user.[…]"

Include a diagram which shows the relations among concepts.

This section is important because it outlines the concepts that you will later implement. In particular, the diagram defined here will follow you throughout the project report and you will be adding more details to it.

Main Concepts

1. User:

Represents an individual using the system.

Attributes:

  • User ID, name, email, role (e.g., team member or admin).

Relations:

  • Can create and assign tasks.
  • Can belong to one or more teams.

2. Task:

Represents a unit of work to be done.

Attributes:

  • Task ID, title, description, status (e.g., pending, in-progress, completed), priority, deadline.

Relations:

  • Belongs to a project.
  • Assigned to one user only.

3. Team:

Represents a group of users working collaboratively.

Attributes:

  • Team ID, name, description, members.

Relations:

  • Can own multiple projects.
  • Can collaborate on tasks.

4. Project:

Represents a collection of tasks grouped by a specific goal or objective.

Attributes:

  • Project ID, name, description, creation date, due date.

Relations:

  • Contains multiple tasks.
  • Associated with a specific team.

5. Category:

Represents a classification for tasks to help in organization (e.g., "Bug Fixes," "Features").

Attributes:

  • Category ID, name.

Relations:

  • Assigned to one or more projects.

Diagram that shows the relationship among concepts

Relationship-Diagram.png

API uses

📑  Content that must be included in the section Describe at least one client and one service that could use your Web API. You must explain here what is the functionality provided by the client/service, and how it uses the Web API to implement this functionality.

1. Client: Task Manager Web Application

Functionality:
The web application for managing tasks allows users to generate tasks, assign them to teams, assign deadlines, organize tasks by categories, and collaborate through comments using a web UI.

How it utilizes the Web API:

  • User Authentication & Profiles:
    The web application utilizes the Web API for authenticating users and retrieving profile information (e.g., GET /users/{id}), for secure access to task management operations.

  • Task Operations:

    • Creation/Removal: Users can create tasks through POST /tasks and delete them through DELETE /tasks/{id}.
    • Modification: Status of a task (e.g., "completed") is updated through PATCH /tasks/{id}.
    • Filtering: Filter tasks through categories or deadlines through queries such as GET /tasks?category=Work.

  • Team Collaboration:

    • Teams are created with POST /teams, and assigning them to a task is through PUT /tasks/{id}/assign.
    • Real-time feedback for task assignments through WebSocket integration.

  • Hypermedia Navigation:
    The application takes advantage of _links values in API responses (e.g., "comments": "/tasks/1/comments") for dynamically loading related resources such as comments.

2. Service: Analytics & Reporting Engine

Functionality:
The backend service performs automated reporting for completion of tasks, productivity of teams, and compliance with deadlines and sending out warnings for overdue tasks.

How it utilizes the Web API:

  • Data Gathering:
    Retrieves task data nightly through GET /tasks?status=overdue and team statistics through GET /teams.

  • Report Creation:
    Stores aggregated reports (e.g., "Team A completed 90% of tasks") through POST /reports.

  • Notifications:
    Triggers email/Slack notifications through combining task deadlines (GET /tasks?deadline=today) and contact information for teams (GET /teams/{id}.

  • Scalability:
    Employs pagination (GET /tasks?page=2) and caching to manage big data effectively.

Related work

📑  Content that must be included in the section Find at least one API that resembles the functionality provided by yours. Explain in detail the functionality provided by the API. Classify the API according to its type (RPC, CRUD REST, pure REST, hypermedia driven ...) justifying your selection. Provide at least one example client that uses this API.

The purpose of this task is to get more familiar with what an API is. This will be helpful in describing your own API. Therefore, it is recommended to do this section after you have decided the topic of your project but before writing your API description.

1. Trello API

Functionality: Uses a board-card-list model for task management through its API. Features include creation/assigning of a card (task), due date, labels, comments, file uploads, and collaboration with a team through boards.

API Type: CRUD REST
Justification:

  • Employs RESTful endpoints (e.g., POST /cards, PUT /cards/{id}) with default HTTP operations (GET, POST, PUT, DELETE).
  • Doesn't use hypermedia (HATEOAS); endpoint discovery happens through static documentation.

Example Client:

  • Zapier integrates Trello with applications such as Gmail. Example: creating a Trello card out of an email:
    POST /cards with payload: { "name": "Urgent Task", "due": "2023-12-10", "idList": "list_id" }.

2. GitHub Issues API

Functionality: Tracks software development project jobs (issues) with assignment, labels, milestones, comments, and filtering by issue state (open/closed).

API Type: Hypermedia-driven REST
Justification:

  • Responses contain hypermedia links (e.g., comments_url in issue responses).
  • Clients navigate dynamically through embedded links (HATEOAS compliance).

Example Client:

  • ZenHub synchronizes with GitHub Issues for statistics. Example request:
    GET /repos/{owner}/{repo}/issues returns issues with comments_url links.

3. Comparison to Our API

Feature Our API Trello API GitHub Issues API
HTTP Methods Full CRUD + PATCH CRUD CRUD + Hypermedia
Hypermedia Yes (_links fields) No Yes
Real-Time Updates WebSocket Webhooks Webhooks
Task Organization Categories/Teams Boards/Lists Labels/Milestones

Why Trello is Closest: Trello's use of CRUD and its task-focussed model map onto our API, but extend it with hypermedia for discoverability and a built-in analytics service.

Use of AI

📝 We used ChatGPT to brainstorm ideas and breakdown the work and help with writing descriptions.

Resources Allocation

Task Student Estimated Time
Deliverable 1 - Project Plan
Task 1: API Overview Abdullah 2 hours
Task 2: Main Concepts and Relations Diagram Uswah 3 hours
Task 3: API Uses Hassan 4 hours
Task 4: Related Work Mathéo 3 hours
Task 5: Review and Coordination All Students 2 hours
Deliverable 2 - Database
Task 6: Database Design and Main Entities Mathéo & Hassan 5 hours
Task 7: API Implementation - Database Integration Abdullah & Uswah 5 hours
Task 8: Review and Coordination All Students 5 hours
Deliverable 3 - API Implementation
Task 9: API Implementation - User Management Abdullah 8 hours
Task 10: API Implementation - Project Handling Uswah 7 hours
Task 11: API Implementation - Task Handling Mathéo 5 hours
Task 12: API Implementation - Real-time Updates Hassan 5 hours
Task 13: API Implementation - LLM API Integration Abdullah & Uswah 5 hours
Task 14: Review and Coordination All Students 10 hours
Deliverable 4 - API Documentation and Hypermedia
Task 15: Documentation - User Guide Mathéo 7 hours
Task 16: Documentation - API Reference Hassan 6 hours
Task 17: Hypermedia Integration Abdullah & Uswah 2 hours
Task 18: Review and Coordination All Students 5 hours
Deliverable 5 - API Use
Task 19: API Integration in Web App Abdullah 12 hours
Task 20: API Integration in Backend Server Uswah 12 hours
Task 21: Testing and Debugging Mathéo & Hassan 6 hours
Task 22: Review and Coordination All Students 5 hours
Final Deliverable - Reflection and Feedback
Task 23: Reflection and Feedback All Students 15 hours

Report index

Clone this wiki locally