Skip to content

API description

Jump to bottom
Harry Nguyen edited this page Feb 13, 2026 · 17 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[...]“

✏️ ChillSense is a RESTful web API to manage a Cold Chain system, which monitors the temperature of sensitive cargo like vaccines and frozen food during their transport. If a trucks freezer fails to maintain the cargo at the predefined temperature, the company must be notified immediately to take proper measures, not after the truck arrives at the destination and the cargo has been spoiled.

The context: Imaginary Architecture

Our API serves as a backend for a larger logistics platform. Of course we are building only the API here, but the full imaginary system would include these:

  1. Sensors which are the data producers in the system. They wake up every few minutes to measure temperature and humidity.

  2. ChillSense API which is our component. It receives the data sent by sensors and validates the safety rules and automatically creates an alert if it detects a violation. It also keeps a secure audit log of all user actions.

  3. Dashboard which is a data consumer and is in fact a web interface for logistics management. The managers can see which trucks are currently RED (unsafe) and which ones are GREEN (safe).

  4. Alerting Service which is a background worker that fetches the list of active alerts from the API. If it finds a new alert that was created by the API logic, it triggers a notification via email or SMS.

Our API is the intermediate stage between trucks and the managers' screen. It keeps our data clean, by blocking invalid readings like impossible temperatures, and can be used as a reliable source of truth for retrieving shipment logs.

Main API Endpoints

Services Method Endpoints example Description
Sensors/Simulator POST /api/shipments Create a (fake) shipment
Sensors/Simulator POST /api/shipments/{shipment_id}/readings/ Add a reading for a shipment (auto-create alert as business logic)
Dashboard POST /api/shipments Create a shipment
Dashboard PUT /api/shipments/{shipment_id}/ Update a shipment
Dashboard DELETE /api/shipments/{shipment_id}/ Delete a shipment
Dashboard GET /api/shipments/ List all shipments
Dashboard GET /api/shipments/{shipment_id}/ Get shipment details and all readings
Dashboard PUT /api/alerts/{alert_id}/ Update an alert
Alerting/Monitor GET /api/alerts Get current alerts

Main concepts and relations

📑  Content that must be included in the section Identify and 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.

✏️ We have defined four main concepts that map to real-world logistics entities:

  1. Shipment This is a single trip that a truck has. It acts as the container for the data.

    • It has static details like origin and destination and of course a cargo name to distinguish between different cargo containers and make it easier to distinguish them from each other.
    • It includes status and created_at to track the trips' lifecycles.
    • It also defines the safety rule which is made of minimum temperature and maximum temperature for each type of the cargo. For example, a truck transporting bananas may need to keep the temperature between 12 and 14 degrees Celsius. This is obviously different if the truck is carrying a shipment of vaccines.

  2. Reading This is the telemetry data sent by the trucks.

    • The values that are sent are dynamic: temp (temperature), humidity, ts (timestamp).
    • Relation: A reading cannot exist on its own and needs to be linked to a specific shipment (using shipment_id) to make sense.
    • Identity: A reading is uniquely identified by the combination of its shipment_id and timestamp because a single shipment cannot have two readings at the exact same millisecond.

  3. Alert An alert is a persistent entity in our database, not just a notification. This is actually a key concept for the user.

    • An alert exists when a specific reading violates the temperature minimum/maximum constraints of its shipment.
    • It includes fields like severity, msg, and is_resolved so we can track if a manager has handled the issue.
    • Relation: Relation: It belongs to a specific shipment and references the specific reading that caused the violation.

  4. AuditLog This is a security concept that we added to provide full system transparency to make sure we know who did what.

    • It makes the system keep a secure audit trail. It records all critical actions like modification of a safety rule or resolution of an alert.
    • It stores the action, details and ts (timestamp) to provide a history of all changes.

Concept Diagram

classDiagram
    class Shipment {
        Integer id
        String name
        String status
        String origin
        String destination
        Float min_temperature
        Float max_temperature
        DateTime created_at
    }
    class Reading {
        Integer id
        Float temp
        Float humidity
        DateTime ts
        Integer shipment_id
    }
    class Alert {
        Integer id
        String msg
        String severity
        Boolean is_resolved
        DateTime created_at
        Integer shipment_id
        Integer reading_id
    }
    class AuditLog {
        Integer id
        String action
        String details
        DateTime ts
    }

    Shipment "1" -- "many" Reading : has
    Shipment "1" -- "many" Alert   : has
    Alert "1"    -- "1" Reading    : belongs_to
Loading

API consumers

📑  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.

✏️ We have designed our API to support two very different types of consumers:

  1. Machine-to-Machine Services (IoT Simulator) This is a background Python program that acts as the "Data Producer" and we made sure it mimics the physical sensors that are installed on trucks. - Functionality: Its job is to create realistic telemetry data, namely temperature and humidity, and push this data to our system continuously. - How it uses the API: It is a write-heavy client. It uses POST requests to create new shipments at the start of a trip and sends new readings every few seconds. It relies on the API to validate the data format, for example to make sure temperature is a number, and simply waits for a 201 Created confirmation.

  2. Human-usable Client (Logistics Dashboard) This is a web frontend that acts as the "Data consumer". It is the tool managers use to monitor the cargo. - Functionality: It visualizes the health of the supply chain. Managers use it to find trucks that are in a Red state (unsafe) and investigate historical data. - How it uses the API: It is a read-heavy client. It uses GET requests to fetch the list of active shipments. When a manager selects a truck, the dashboard uses the API to get the full history of readings to create diagrams such as line charts. This dashboard relies on the API to filter and aggregate the data so the browser doesn't crash from loading too many points.

Related work

📑  Content that must be included in the section Find at least one API that resembles the functionality provided by yours. Provide a link to the API documentation. 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 with examples from the API.

Finally, provide at least one example client that uses this API explaining a bit what it is doing and how it is using the 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.

✏️

Description and Classification:

Related Work

An industrial example that is relevant to the ChillSense API is the Maersk Captain Peter API, provided by A.P. Moller – Maersk.

Captain Peter is a RESTful API used for monitoring refrigerated shipping containers (reefers). It exposes container telemetry such as temperature, humidity, and location data, allowing external systems to integrate this information into dashboards, alerts, and logistics platforms.

Official documentation: https://developer.maersk.com/api-catalogue/captain-peter

RESTful Characteristics

The Captain Peter API follows core REST architectural principles:

  • Resource-oriented design
    Container telemetry data is exposed as addressable resources.

  • Stateless communication
    Each request contains all required information, including authentication credentials, without relying on server-side session state.

  • Standard HTTP usage and JSON format
    Clients interact with the API using HTTP endpoints and receive structured JSON responses.

  • Client–server separation
    The backend monitoring system is decoupled from client applications that consume the data.

Although access to the API requires credentials and is for enterprise use, the design follows RESTful practices of production systems.

Client Example

A typical client of the Captain Peter API is a logistics or monitoring service that retrieves container condition data and visualizes it in a dashboard or creates alerts when threshold are violated.

A conceptual interaction with the API is shown below:

GET /v1/captain-peter/containers/{containerId}/telemetry

Authorization: Bearer ACCESS_TOKEN

Example JSON response:

{
  "containerId": "ABC1234567",
  "temperature": 3.4,
  "humidity": 82,
  "timestamp": "2026-01-22T15:14:00Z"
}

The client processes this response to display real-time container conditions or to detect and report anomalies.

Use of AI

📝 If you have use AI during this deliverable, explain what tool/s you have used and how.

AI use

  • We designed the database schema on paper and defined the entities and relationships ourselves, but used Gemini to convert that design into the correct Mermaid.js syntax for the Wiki diagram.
  • We discussed and developed API Endpoints using word docs and sample code; just used ChatGPT to make it pretty in table format.
  • We used AI as a proofreading tool to correct typos.

Resources allocation

Task Student Estimated time
Project idea and discussion Hieu Nguyen and Sajjad Ghaeminejad 9 hours
Architecture and database design Hieu Nguyen and Sajjad Ghaeminejad 4 hours
Study and research: learning flask basics & Mermaid syntax Sajjad Ghaminejad 4 hours
Initial project setup (Repo/Wiki) Sajjad Ghaeminejad 1.5 hour
Writing Deliverable 1 Sajjad Ghaeminejad 4.5 hours
Study and research: learning flask basics and its API method Hieu Nguyen 1.5 hours
Reviewing, Discussing & Updating Deliverable 1 Hieu Nguyen 3 hours

Report index

Clone this wiki locally