Analysis of client-sided REST api calls and server-sided endpoints #8594
Assignees
Labels
feature-proposal
This issue is a feature proposal
Comments
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Feature Proposal
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
Non-Functional Requirements
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
.jsonfiles 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": [ { "file_path": "path/to/server/file.java", "RequestMapping": "/api", "endpoints": [ { "method_name": "handleGetRequest", "rest_url": "/example", "HTTP_method_annotation": "getMapping", "line": "21" }, { "method_name": "handlePostRequest", "rest_url": "/example", "HTTP_method_annotation": "postMapping", "line": "42" } ] }, { "file_path": "path/to/another/server/file.java", "RequestMapping": "/api", "endpoints": [ { "method_name": "handleAnotherGetRequest", "rest_url": "/anotherExample", "HTTP_method_annotation": "getMapping", "line": "64" } ] } ] }The text was updated successfully, but these errors were encountered: