Development: Analyze REST calls and endpoints

[Jan-Thurner]

Checklist

General

• Language: I followed the guidelines for inclusive, diversity-sensitive, and appreciative language.
• I chose a title conforming to the naming conventions for pull requests.

Context

Building on the functionality introduced in the previous PRs, where we successfully parsed information regarding changed server endpoints and client-sided REST api calls, the proposed feature aims to take the parsing a step further. The new feature will introduce the comparison and analysis of client-sided REST calls against server-sided endpoints. By cross-referencing the HTTP methods and URLs used in client requests with the server endpoints, we can identify mismatches, inconsistencies, and potential errors in the API interactions between the client and server. This comparison will enhance our ability to ensure that the client and server components are correctly aligned, thereby improving the reliability and robustness of the application.

Problem

The problem tackled in this issue is the potential for discrepancies and misalignments between client-sided REST calls and server-sided endpoints, which can lead to broken functionality and increased debugging time. Currently, developers must manually ensure that the client and server communicate correctly. Manual verification is not only labor-intensive but also susceptible to oversights, leading to potential bugs and degraded user experience. Without automated verification, mismatches in URLs, HTTP methods, and expected data formats can easily slip through code reviews and testing phases, causing features to fail in production. This issue addresses the need for an automated solution to compare and analyze client-sided REST calls against server-sided endpoints, ensuring consistency and correctness across the application and reducing the risk of integration errors.

Motivation

The motivation behind this feature is to enhance the robustness and reliability of the Artemis application by automating the verification of API interactions between client and server. Ensuring that client-sided REST calls match the server-side endpoints is crucial for seamless functionality, user satisfaction, and overall system integrity. By implementing automated comparison and analysis, we can proactively identify and resolve discrepancies early in the development process, reducing the time spent on debugging and improving development efficiency. This feature will empower developers with more accurate insights, streamline the code review process, and ultimately contribute to a more stable and reliable application.

Requirements Engineering

Existing (Problematic) Solution / System

Currently, the existing solution comprises two separate GitHub Actions developed in previous PRs. The first action parses information related to changed server endpoints, providing insights into modifications on the server side. The second action extends this functionality by parsing client-sided REST calls, extracting details such as HTTP methods and URLs used in client requests. However, these actions operate independently and do not offer a mechanism for cross-referencing or comparing client-side REST calls with server-side endpoints. As a result, while they provide valuable information individually, they do not address the need for ensuring consistency and alignment between the client and server API interactions, which is critical for maintaining application integrity.

Proposed System

The proposed system is an integrated solution that automates the verification of API interactions between the client and server, ensuring that client-sided REST calls are correctly aligned with server-side endpoints. This system would significantly reduce the manual effort required for verifying API interactions, enhance the accuracy and reliability of client-server communication, and ultimately lead to higher code quality and more stable applications. To verify the API interactions, the system identifies REST calls and endpoints in modified files and checks if there are endpoints matching the REST calls and REST calls using the endpoints. If there is no endpoint matching a specific REST call, the system will identify it and output a warning to the console. If an Endpoint is not used by any REST call of the Client, the system will print a warning, too.

Requirements

Functional Requirements

1. FR: Compare REST calls with the server: The system must check that every client-sided REST call in a modified file has a matching endpoint on the server-side.
2. FR: Compare endpoints with the client: The system must check that every endpoint in a modified file on the server is used by at least one REST call by the client.
3. FR: Real-Time Feedback: The system must provide real-time feedback on detected inconsistencies between client-sided REST calls and server-side endpoints during the development process, through a GitHub action.
4. FR: Comprehensive Reporting: The system must generate detailed reports on the status of API interactions modified in a PR, highlighting detected mismatches.
5. FR: Integration with CI/CD Pipelines: The system must integrate with existing CI/CD pipelines to automate the verification of API interactions as part of the deployment workflow.

Non-Functional Requirements

1. NFR: Performance (Scalability): The system must process and analyze codebases with up to 1 million lines of code within 30 minutes to ensure efficient handling of large projects.
2. NFR: Extendability: The system must include comprehensive documentation and modular components, allowing new developers to understand and start working on the system within 2 days and enabling minor updates or bug fixes to be implemented within 1 hour.
3. NFR: Usability: The system must provide an interface that allows developers to access reports within 5 clicks or less, ensuring quick and intuitive interactions.

Analysis

Analysis Object Model

This model depicts an abstract structure of how REST methods (e.g., GET, POST, PUT, DELETE) are integrated into a software system. To be able to call a REST method, there needs to be a call to a REST endpoint and the REST endpoint itself. A REST method is called by the client. The call happens within a Java method call. The respective REST endpoint is located on the server. Each endpoint is contained in its own Java method.

Dynamic Behavior

The following model illustrates the process of parsing and analyzing client-sided REST calls and server-sided endpoints within a software project, focusing on files modified in a PR. First, the system identifies all files that have been modified in the current pull request. Once these files are identified, the system proceeds to parse both server-sided and client-sided endpoints separately.

For server-sided endpoints, the system searches for methods within the server files. Upon finding methods, the system checks whether any of these methods serve as server endpoints. If a method is identified as an endpoint, the relevant information, such as the HTTP method and URL, is parsed and stored for further analysis.

Similarly, the system handles client-sided endpoints. The system looks for methods within client files. If methods are found, the system then determines whether any of these methods contain REST calls. If a method containing a REST call is found, the system parses the relevant information, such as the HTTP method and URL, and stores it for further analysis.

After parsing both client-sided and server-sided files, the system checks if an endpoint is accessed by one ore more REST calls. If matching REST calls are found, the REST calls and the endpoint will be printed to the GitHub action. If there is no matching REST call found, a warning containing the unused endpoint will be printed to the actions output. Similarly, the system will check for every REST call, if there is exactly one matching endpoint on the server. If so, the system will print the REST call and the corresponding endpoint to its output. If there are more ore less then one matching endpoint, the software will print another warning containing the REST call and the duplicate or missing endpoints.

The software detects any inconsistencies or mismatches between the client-sided REST calls and the server-sided endpoints. This thorough analysis ensures that the client and server components are synchronized, thereby improving the overall reliability and usability of the system.

System Architecture

Subsystem Decomposition

The system is split into four distinct subsystems. The first subsystem identifies all files that are modified within a PR.

The second subsystem parses the modified server files regarding their endpoints. It extracts and stores relevant information like the endpoint's path, name, and the HTTP method it is using.

The third subsystem parses the modified client files regarding the REST calls used. It stores relevant information like the REST call's path, the HTTP method used, and the function's name.

The fourth subsystem analyzes and compares the data regarding server endpoints and client REST calls, gathered by the second and third subsystem. The system identifies issues like mismatches in client- and server-sided URLs and missing endpoints on the server. It prints a concise summary of its findings, improving and simplifying the review process.

This decomposition into specialized subsystems facilitates a modular approach, making the system easier to develop, maintain, and extend.

Persistent Data Management

The findings by the second and third subsystems are to be stored in .json files within the GitHub action. The fourth subsystem can then read the information from the files and process and analyze it.

The .jsonfile containing the information parsed from the client files will look like this:

{
  "version": "1.0.0",
  "client_files": [
    {
      "file_path": "path/to/client/file.ts",
      "rest_calls": [
        {
          "rest_url": "/api/example",
          "rest_method_type": "GET",
          "line": "21",
        },
        {
          "rest_url": "/api/example",
          "rest_method_type": "POST",
          "line": "42",
        }
      ]
    },
    {
      "file_path": "path/to/another/client/file.ts",
      "rest_calls": [
        {
          "method_name": "anotherGetMethod",
          "rest_url": "/api/anotherExample",
          "rest_method_type": "GET",
          "line": "21",
        }
      ]
    }
  ]
}

The .jsonfile containing the information parsed from the server files will look like this:

{
  "version": "1.0.0",
  "server_files": [
    {
      "filePath": "path/to/server/file.java",
      "classRequestMapping": "/api",
      "endpoints": [
        {
          "requestMapping": "/api"
          "method_name": "handleGetRequest",
          "URI": "/example",
          "httpMethodAnnotation": "getMapping",
          "className": "ExampleClass",
          "line": "21"
          "otherAnnotations": []
        },
        {
          "requestMapping": "/api"
          "method_name": "handlePostRequest",
          "URI": "/example",
          "httpMethodAnnotation": "postMapping",
          "className": "ExampleClass",
          "line": "42"
          "otherAnnotations": []
        }
      ]
    },
    {
      "filePath": "path/to/another/server/file.java",
      "classRequestMapping": "/api",
      "endpoints": [
        {
          "requestMapping": "/api"
          "method_name": "handleAnotherGetRequest",
          "URI": "/anotherExample",
          "httpMethodAnnotation": "getMapping",
          "className": "ExampleClass",
          "line": "64"
          "otherAnnotations": []
        }
      ]
    }
  ]
}

Steps for Testing

1. Navigate to the GitHub action's output
2. Take a look at the output of tab analyze endpoints and decide if it is comprehensive and concise, or if there are things that need to be improved
3. Take a look at the output of tab analyze rest calls and decide if it is comprehensive and concise, or if there are things that need to be improved

Testserver States

Note

These badges show the state of the test servers.
Green = Currently available, Red = Currently locked

Review Progress

Performance Review

• I (as a reviewer) confirm that the client changes (in particular related to REST calls and UI responsiveness) are implemented with a very good performance
• I (as a reviewer) confirm that the server changes (in particular related to database calls) are implemented with a very good performance

Code Review

• Code Review 1
• Code Review 2
• Code Review 3
• Code Review 4

Test Coverage

unchanged

Screenshots

Summary by CodeRabbit

Summary by CodeRabbit

• New Features

  • Introduced classes for managing and analyzing endpoint connections, including EndpointAnalyzer, RestCallAnalyzer, and RestCallInformation.
  • Added structured records such as EndpointInformation and RestCallInformation to enhance data management for endpoints and REST calls.

• Improvements

  • Enhanced workflow for analyzing endpoint connections and REST calls with a clearer job structure and modularity.
  • Streamlined artifact management with more descriptive naming conventions for better clarity and understanding.
  • Improved analysis processes by separating parsing and analysis into distinct phases.

• Bug Fixes

  • Resolved issues with file handling in workflows, improving the execution of parsing scripts for REST API calls.

[coderabbitai]

Actionable comments posted: 1

[JohannesStoehr]

Code

[az108]

LGTM after changes, reapprove

[pzdr7]

Code

[florian-glombik]

Approve code, thanks for addressing the change requests!

[sarpsahinalp]

Code lgtm, github workflow seems to be working as expected!

[BBesrour]

code lgtm

[MarkusPaulsen]

Further follow-up: Check how many public methods can be made (package-)private.

Aside from that, the code looks good. Tested on https://github.com/ls1intum/Artemis/pull/8771/checks.