{"id":24196937,"url":"https://github.com/souhailas/apicture","last_synced_at":"2025-09-21T21:32:06.780Z","repository":{"id":188037289,"uuid":"653131855","full_name":"souhailaS/APIcture","owner":"souhailaS","description":"APIcture is a CLI to analyse histories of Web APIs, and generate visualisations and metrics starting from repositories containing OpenAPI spec or backends written in Express.js.  ","archived":false,"fork":false,"pushed_at":"2024-06-18T12:11:19.000Z","size":17941,"stargazers_count":5,"open_issues_count":10,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-01-03T12:37:28.266Z","etag":null,"topics":["api","openapi","visualization","webapi"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/apict","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/souhailaS.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-06-13T13:14:30.000Z","updated_at":"2024-11-28T08:28:02.000Z","dependencies_parsed_at":"2023-08-15T11:01:08.002Z","dependency_job_id":"cbb50734-0acf-47c5-8aa8-3e175ce33aac","html_url":"https://github.com/souhailaS/APIcture","commit_stats":null,"previous_names":["souhailas/apicture","souhailas/web-api-evolution-visualizations-cli"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/souhailaS%2FAPIcture","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/souhailaS%2FAPIcture/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/souhailaS%2FAPIcture/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/souhailaS%2FAPIcture/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/souhailaS","download_url":"https://codeload.github.com/souhailaS/APIcture/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":233800034,"owners_count":18732284,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","openapi","visualization","webapi"],"created_at":"2025-01-13T19:39:37.329Z","updated_at":"2025-09-21T21:32:00.521Z","avatar_url":"https://github.com/souhailaS.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n\u003c!-- # Interactively exploring API changes and versioning consistency\n\nOur [paper](./VISSOFT_2023_accepted.pdf) is based on APIcture, a novel tool that addresses the need for comprehensive and intuitive visualization of web API evolution.\nWe invite the Artifact Evaluation Committee to evaluate the practicality and effectiveness of APIcture for the reproducibility of the\nvisualization we included in our paper and published in the online gallery: https://souhailas.github.io/VISSOFT2023/\n\n\n- This README.md is also available in a PDF readable format [here](./2023_VISSOFT_Artifact.pdf) \n\n- The reproducibility guide is detailed in [Reproducing the visualizations in the VISSOFT paper Section](#reproducing-the-visualizations-in-the-vissoft-paper) of this document. --\u003e\n\n# APIcture\n\nAPIcture is a comprehensive tool designed to empower researchers, developers, and users to gain deeper insights into\nthe evolution of web APIs. It introduces an innovative approach to visualizing API changes and\nversioning strategies, enabling users to comprehend the temporal sequence of changes, assess compatibility issues, and\nunderstand versioning practices. The tool encompasses two main visualizations: API Changes and API Version Clock.\nThe former provides a detailed view of changes occurring at specific time intervals, while the latter offers an overarching\nview of version upgrades and change patterns. Our Artifact Evaluation submission presents APIcture, detailing its\nfunctionality, utilization, and practicality to generate API evolution visualizations. We provide clear instructions on\nhow to reproduce our visualization and explore other API evolution cases.\n\n\nFind visualizations explanation details in [1].\n\nAPIcture serves also to generate evolution metrics and their visualizations. \n## Usage guide\n\n### Installation\n\nTo start using APIcture, you need to install the CLI tool. Follow these steps:\n\n\n   * Install Node.js and npm: APIcture requires Node.js and npm (Node Package Manager) to be installed on your system. If you haven’t already installed them, you can download them from the official Node.js website: https://nodejs.org/\n      Minimum required compatible version is:v16.18.\n\n   * Install the latest Golang version suitable to your machine: https://go.dev/dl/\n\n   * Install APIcture using the command: `npm install apict -g`\n\nTo be sure that APIcture is properly installed, run: `apict -v` of `apict --version` this should display the current version of the artifact. \n\n### Basic usage\n\nAPIcture offers various subcommands that cater to different aspects of API visualization. Here are the fundamental\nsteps to get started with APIcture:\n\n* **Main subcommands:** To generate the visualizations, run theapictcommand followed by the desired subcom-\nmand and any additional options to generate the desired visualizations. The available subcommands include:\n\n   - `apict \u003cspec-path\u003e`: Generates visualizations for the OpenAPI specification located at the specified path.\n   - `apict changes \u003cspec-path\u003e`: Focuses specifically on changes localization.\n   - `apict clock \u003cspec-path\u003e`: Analyzes version upgrades versus changes types.\n   - `apict metrics`: Generates visualizations for API metrics.\n* **Subcommands available options:** APIcture provides several options (Figure 1) to customize the visualization\nprocess according to the users needs:\n- -r, –repo \u003crepo\u003e: Specifies the path to the repository containing the API’s version history. By default, the tool\nuses the current working directory as the repository location.\n- -o, –output \u003cpath\u003e: Defines the path to the output directory where the generated visualizations will be saved.\nIf not specified, the output will be saved in the default directory.\n- -fs, –fast: Activates the fast mode, which optimizes the execution for faster generation of visualizations. This\nmode is only activable if the visualization has been already generated in normal mode. If not, this option is\nignored.\n- -f, –format \u003cformat\u003e: Specifies the desired output format for the generated visualizations. The available\nformats include options such as PNG, SVG, and interactive HTML.\n- -a, –all: Generates OpenAPI specifications for all OpenAPI files found in the repository. This option facilitates\ngenerating visualizations for multiple specifications within the same repository.\n- -fn, –filename \u003cfilename\u003e: Specifies the output file name for the generated visualization. The tool saves the\nvisualization with the specified file name (without file extension) in the output directory.\n- -h, –help: Displays the help information for the command, providing a concise overview of the available\noptions.\n- -v, –version: Displays the current version of the tool.\n- -c, -clean: Deletes the artifacts used in the fast mode.\n\n![Help Subcommand](./figures-artifact/help.png)\n\u003cp style=\"text-align: center;\" \u003e\u003cem \u003eFigure 7: Help Subcommand\u003c/em\u003e\u003c/p\u003e\n\n### Use case example\n\nThis section provides comprehensive instructions for generating visualizations from a real world repository using the\ncommands and options listed earlier.\nFor illustrative purposes, we have included sample API GitHub repositories containing OpenAPI specifications in\nour GitHub Repository (https://github.com/souhailaS/APIcture/blob/main/git_urls.json).\n\n\nWe pick the OpenAI API project (https://github.com/openai/openai-openapi.git) as our example. Begin by cloning the repository to your local machine:\n\n```\ngit clone https://github.com/openai/openai-openapi\n```\n\nNext, navigate into the repository:\n```\ncd openai-openapi\n```\n\nFigure 8 depicts the structure of the OpenAI API repository, revealing the top-level placement of the OpenAPI\nspecification file (openapi.yaml).\n\n![Repository Structure: OpenAI API](./figures-artifact/clone.png)\n\u003cp style=\"text-align: center;\" \u003e\u003cem \u003eFigure 8: Repository Structure: OpenAI API\u003c/em\u003e\u003c/p\u003e\n\nTo generate all evolution visualizations at once, simply execute: `apict`.\nAlternatively, utilize the `apict` command with the `-r` option, which will run the visualizations generation without need to navigate to the repository:\n\n```\napict -r openai-openapi\n```\n\nIn the absence of a specific file path, APIcture automatically locates all OpenAPI specification files within the\nrepository and prompts the user to select one (Figure 9).\n\n![apict Command Line: Generating Visualizations](./figures-artifact/apict.png)\n\u003cp style=\"text-align: center;\" \u003e\u003cem \u003eFigure 9: apict Command Line: Generating Visualizations\u003c/em\u003e\u003c/p\u003e\n\nTo generate visualizations for all OpenAPI specifications within the repository, apply the `-a [–all]` option:\n\n\n```\napict -r openai-openapi -a\n```\n\n\n\n\n\nGenerated visualizations are stored within theAPIcturefolder, organized under a directory named after the respective\nspecification. For instance, in this case, the visualizations are located withinAPIcture/openapi (Figure 12). \n\n![apict command outputs](./figures-artifact/outputs.png)\n\u003cp style=\"text-align: center;\" \u003e\u003cem \u003eFigure 12: apict command outputs\u003c/em\u003e\u003c/p\u003e\n\nBy default, if no format is given, the output format is HTML.\nThe generated HTML files are:\n\n- changes-\u003copenapi api file name\u003e.html: an interactive format of the API Changes visualization.\n- version-clock-\u003copenapi api file name\u003e.html: an interactive format of the API Version Clock visualization.\n- version-clock-\u003copenapi api file name\u003e.html: an interactive format of six API evolution metrics plots (Figure 10).\n\n![apict metrics visualization](./figures-artifact/metrics.png)\n\u003cp style=\"text-align: center;\" \u003e\u003cem \u003eFigure 10: apict metrics visualization\u003c/em\u003e\u003c/p\u003e\n\n- viz-\u003copenapi api file name\u003e.html: a single HTML page that includes all the previous interactive visualiza-\n    tions, in addition to a header showing history related metadata (Figure 11).\n\n![apict output evolution visualizations](./figures-artifact/viz.png)\n\u003cp style=\"text-align: center;\" \u003e\u003cem \u003eFigure 11: apict output evolution visualizations\u003c/em\u003e\u003c/p\u003e\n\nWhen executing the `apict` command without specifying any additional options, it initiates the process of generating\nan evolution report directly within the terminal (Figure 13). Furthermore, for users seeking to access this report\nindependently of the complete visualization generation process, the report subcommand can be employed.\n\n```\napict report -r openai-openapi\n```\n\nRather than being limited to using only the overarching `apict` command, users have the flexibility to employ focused\nsubcommands. Each of these subcommands generates a specific output individually, allowing for a more tailored\napproach to visualization creation. In addition to this, the–fastoption is provided to optimize the time taken in the\ngeneration process, particularly when users are exclusively interested in obtaining a particular output. This approach\nstreamlines the generation time, making the process more efficient and relevant to the specific visualization needs of\nthe user.\n\n\n![apict terminal prompt](./figures-artifact/report.png)\n\u003cp style=\"text-align: center;\" \u003e\u003cem \u003eFigure 13: apict terminal prompt\u003c/em\u003e\u003c/p\u003e\n\n### Other supported cases\n\nIn scenarios where no OpenAPI file is detected within the repository (Figure 14), APIcture employs a distinct approach\nfor Express.js projects. It systematically generates a corresponding OpenAPI specification from the project’s codebase\nfor each commit existing in the repository’s history. Subsequently, APIcture selects the specifications that exhibit\ndifferences from the specification of the preceding commit. This generation process leverages [ExpressO[2]](https://www.npmjs.com/package/expresso-api) a CLI tool\ndesigned to validly generate OpenAPI specifications from expressjs code. The generated specifications are then utilized\nby APIcture to generate the intended visualizations.\nIn the case where the project’s dependencies are not already installed, select(x) Nothen rerun theapictcommand.\nIt is important to note that the showcased examples within our published gallery exclusively originate from projects that\nfeature an accessible OpenAPI specification within the repository. In this version of APIcture, the effective generation of\nvisualizations through Express.js code hinges on the capability of ExpressO to construct a specification from the underlying\ncodebase.\n\n![APIcture - No OpenAPI File](./figures-artifact/noOAS.png)\n\u003cp style=\"text-align: center;\" \u003e\u003cem \u003eFigure 14: APIcture - No OpenAPI File\u003c/em\u003e\u003c/p\u003e\n\n\n### Reproducing the visualizations in the VISSOFT paper\n\nTo facilitate the reproducibility of the visualizations showcased in the public gallery, we have introduced a temporary command that streamlines the generation of all visualizations in a single run:\n\n`apict vissoft`\n\nBy executing this command, APIcture automatically clones a predefined list of GitHub repository URLs, thoughtfully provided within the APIcture repository. It is important to note that an active internet connection is required to retrieve these Git repositories from GitHub. The command subsequently generates visualizations for all the cloned repositories, and as an added benefit, it creates an index.html page. This page serves as a convenient navigation hub, allowing users to seamlessly explore and access all the generated visualizations in a coherent manner.\n\nWhen utilizing the command apict vissoft, users will initially be prompted to provide  the JSON file containing the array of URLs of the repositories to clone, and a destination folder path where the repositories will be cloned. The JSON file can be downloaded from: [https://github.com/souhailaS/APIcture/blob/main/git\\_urls.json ](https://github.com/souhailaS/APIcture/blob/main/vissoft/git_urls.json). You can customize this file and remove some of the URLs if you want to test it with fewer URLs (Figure 1). \n\n***If no path of the JSON file containing the URLs of the repositories to clone is given or the inserted path is invalid, it will be defaulted to the git_urls.json included in APIcture's repository.  In case the user opts not to input any path, the current location will automatically be designated as the destination folder for the cloned repositories***\n\n\n![Console after running apict vissoft ](./figures-artifact/vissoftprompt1.png)\n\u003cp style=\"text-align: center;\" \u003e\u003cem \u003eFigure 1: Console after running apict vissoft\u003c/em\u003e\u003c/p\u003e\n\n\n\n If the specified destination folder does not exist, the tool will automatically create it. The repositories are then cloned one after the other showing in the console the state of the cloning phase (Figure 2).\n\n ![Console showing the progress of the projects cloning phase ](./figures-artifact/vissoftprompt2.png)\n \u003cp style=\"text-align: center;\" \u003e\u003cem \u003eFigure 2: Console showing the progress of the projects cloning phase\u003c/em\u003e\u003c/p\u003e\n\n On the other hand, if the folder already exists, the user will be prompted to decide whether they want to completely recreate the folder from scratch and subsequently clone all the repositories into it. If the user chooses not to recreate the folder from scratch, the system will provide information about the number of repositories present within that folder. Following this, the generation of visualizations for the existing APIs in the folder will commence (Figure 3). In scenarios where no repositories are present in the designated folder, the tool will proceed to clone the repositories before initiating the process of visualization generation.\n\n\n ![Cloning destination folder already exists](./figures-artifact/vissoftprompt3.png)\n   \u003cp style=\"text-align: center;\" \u003e\u003cem \u003eFigure 3: Cloning destination folder already exists\u003c/em\u003e\u003c/p\u003e\n\n\nUpon completion of the cloning process, the user will be prompted to specify a path for the destination folder where the resulting visualizations will be stored. In the event that no path is provided, the current directory will be regarded as the destination (Figure 4). \n\n![Destination folder where to save the generated visualizations](./figures-artifact/vissoftprompt4.png)\n\u003cp style=\"text-align: center;\" \u003e\u003cem \u003eFigure 4: Destination folder where to save the generated visualizations\u003c/em\u003e\u003c/p\u003e\n\nSubsequently, a directory named VISSOFT will be established within the designated destination folder. This directory will accommodate the entire collection of generated artifacts. These artifacts encompass individual visualizations for each API, accompanied by an index.html file. The latter functions as a navigational interface, enabling access to each of the generated visualizations (Figure 5).\n\n![Structure of the generated output](./figures-artifact/vissoftoutput.png)\n\u003cp style=\"text-align: center;\" \u003e\u003cem \u003eFigure 5: Structure of the generated output\u003c/em\u003e\u003c/p\u003e\n\nTo generate the outputs APIcture systematically parses all files within the projects with the extensions .yaml or .json, and subsequently assesses whether these files conform to the OpenAPI specification. Upon detecting valid OpenAPI files, the tool proceeds to retrieve their complete version histories. Subsequently, APIcture initiates the generation of visualizations for each identified OpenAPI file, following the comprehensive procedure delineated in Figure 3 of [1](./VISSOFT_2023_accepted.pdf).\n\nIt is important to note that a single repository might contain OpenAPI files pertaining to multiple APIs. To effectively handle this scenario, APIcture structurally organizes the generated outputs, considering both the repository's name and the name of the respective OpenAPI file. \n\nIn the event that the script is terminated during the visualization generation phase and is subsequently restarted, the user will be presented with the choice of either resuming visualization generation for projects that were not previously processed or reinitiating the entire procedure (Figure 6). It is noteworthy that this phase does not necessitate an internet connection. The repositories history is locally fetched from git history.\n\n![Cloned projects have already been processed](./figures-artifact/vissoftprompt5.png)\n\u003cp style=\"text-align: center;\" \u003e\u003cem \u003eFigure 6: Cloned projects have already been processed\u003c/em\u003e\u003c/p\u003e\n\n\n\n\n## Contact\nYou can contact us by email: souhaila.serbout@usi.ch\n\nIssues can be also added to the public repository of APIcture: https://github.com/souhailaS/APIcture. We are currently\nactively enhancing and maintaining it.\n\n\n\n## Extrnal Links\n\n(^1) https://github.com/souhailaS/APIcture/blob/main/vissoft/git_urls.json\n\n(^2) https://github.com/openai/openai-openapi.git\n\n(^3) https://www.npmjs.com/package/expresso-api\n\n(^4) https://souhailas.github.io/VISSOFT2023/\n\n## References\n[1] Souhaila Serbout, Diana Carolina Muñoz Hurtado, and Cesare Pautasso. Interactively exploring API changes and versioning consistency. In 11th\nIEEE Working Conference on Software Visualization (VISSOFT 2023), Bogota, Colombia, October 2023. IEEE. [ 🏆 Best Paper Award]\n\n[2] Souhaila Serbout, Alessandro Romanelli, and Cesare Pautasso. Expresso: From express.js implementation code to openapi interface descriptions. In\nThais Batista, Tomáš Bureš, Claudia Raibulet, and Henry Muccini, editors,Software Architecture. ECSA 2022 Tracks and Workshops, pages 29–44,\nCham, 2023. Springer International Publishing. ISBN 978-3-031-36889-9. [ 🏆 Best Tools and Demos Paper Award]\n\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsouhailas%2Fapicture","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsouhailas%2Fapicture","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsouhailas%2Fapicture/lists"}