{"id":23879523,"url":"https://github.com/linkartemy/outline-vpn-api","last_synced_at":"2025-10-07T03:54:37.937Z","repository":{"id":270519708,"uuid":"909686619","full_name":"linkartemy/outline-vpn-api","owner":"linkartemy","description":"An Outline VPN API Client in C++","archived":false,"fork":false,"pushed_at":"2025-01-20T08:45:10.000Z","size":29,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-22T23:41:19.173Z","etag":null,"topics":["api","asynchronous","boost","cpp","cpp20","outline","outline-vpn","synchronous","vpn","vpn-manager"],"latest_commit_sha":null,"homepage":"https://getoutline.org","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/linkartemy.png","metadata":{"files":{"readme":"README.md","changelog":null,"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":"2024-12-29T13:40:54.000Z","updated_at":"2025-01-20T08:42:31.000Z","dependencies_parsed_at":"2024-12-31T22:25:14.921Z","dependency_job_id":"70434842-6c1c-421d-a1c0-01932d0eb8d2","html_url":"https://github.com/linkartemy/outline-vpn-api","commit_stats":null,"previous_names":["linkartemy/outline-vpn-api-cpp","linkartemy/outline-vpn-api"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/linkartemy/outline-vpn-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/linkartemy%2Foutline-vpn-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/linkartemy%2Foutline-vpn-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/linkartemy%2Foutline-vpn-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/linkartemy%2Foutline-vpn-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/linkartemy","download_url":"https://codeload.github.com/linkartemy/outline-vpn-api/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/linkartemy%2Foutline-vpn-api/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278717449,"owners_count":26033542,"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","status":"online","status_checked_at":"2025-10-07T02:00:06.786Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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","asynchronous","boost","cpp","cpp20","outline","outline-vpn","synchronous","vpn","vpn-manager"],"created_at":"2025-01-03T23:17:33.659Z","updated_at":"2025-10-07T03:54:37.911Z","avatar_url":"https://github.com/linkartemy.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Outline VPN API C++ Client\n\nWelcome to the **Outline VPN API C++ Client**! This library provides a convenient interface for interacting with the Outline VPN server API, enabling you to manage access keys, configure server settings, and monitor server metrics programmatically. All the functionality that is available on the 1st of January, 2025, is supported by the library. \n\n## Table of Contents\n\n- [Features](#features)\n- [Installation](#installation)\n- [Usage](#usage)\n  - [Creating an Access Key](#creating-an-access-key)\n  - [Deleting an Access Key](#deleting-an-access-key)\n  - [Adding a Data Limit](#adding-a-data-limit)\n  - [Retrieving Access Keys](#retrieving-access-keys)\n  - [Managing Server Metrics](#managing-server-metrics)\n  - [Configuring Server Settings](#configuring-server-settings)\n- [Examples](#examples)\n  - [Basic Operations](#basic-operations)\n  - [Advanced Metrics Handling](#advanced-metrics-handling)\n- [API Reference](#api-reference)\n- [Building the Project](#building-the-project)\n- [Contributing](#contributing)\n- [License](#license)\n\n## Features\n\n- **Access Key Management**: Create, get, update, delete, and rename access keys.\n- **Data Limit Control**: Set and remove data usage limits for individual or all access keys.\n- **Server Configuration**: Configure server settings such as server name, hostname and default port.\n- **Metrics Monitoring**: Enable, disable, and get server metrics to monitor usage of trafic.\n- **Asynchronous Operations**: Perform all operations asynchronously for non-blocking execution.\n- **Error Handling**: Comprehensive exception handling for robust and reliable integrations.\n\n## Installation\n\n### Prerequisites\n\nEnsure you have the following dependencies installed:\n\n- **C++ Compiler**: `g++` (version 13 recommended)\n- **Boost Libraries**: System, Asio, JSON, URL components\n- **OpenSSL**\n- **CMake** (optional, if using CMake instead of Makefile)\n- **CURL**\n\n### Building with Makefile\n\n1. **Clone the Repository**\n\n   ```bash\n   git clone https://github.com/linkartemy/outline-vpn-api.git\n   cd outline-vpn-api\n   ```\n\n2. **Build the Project**\n\n   Use the provided Makefile to compile the library and example executable.\n\n   ```bash\n   make all\n   ```\n\n3. **Run the Example**\n\n   ```bash\n   make run\n   ```\n\n4. **Clean Build Artifacts**\n\n   To clean the build directory:\n\n   ```bash\n   make clean\n   ```\n\n### Building with CMake (Optional)\n\nIf you prefer using CMake:\n\n1. **Create a Build Directory**\n\n   ```bash\n   mkdir build \u0026\u0026 cd build\n   ```\n\n2. **Configure the Project**\n\n   ```bash\n   cmake ..\n   ```\n\n3. **Build the Project**\n\n   ```bash\n   make\n   ```\n\n4. **Run the Example**\n\n   ```bash\n   ./example\n   ```\n\n## Usage\n\n### Creating an Access Key\n\nTo create a new access key with specific parameters:\n\n```cpp\n#include \"outline/OutlineClient.h\"\n#include \"outline/utils/UrlUtils.h\"\n\n#include \u003ciostream\u003e\n#include \u003cmemory\u003e\n\nint main() {\n    std::string apiUrl = \"https://your-outline-server.com/api\";\n    std::string cert = \"\"; // Add your server certificate if required\n    int timeout = 10;\n\n    auto client = outline::OutlineClient::create(apiUrl, cert, timeout);\n\n    outline::CreateAccessKeyParams params;\n    params.name = \"NewAccessKey\";\n    params.method = \"AES-256-GCM\";\n    params.password = \"securepassword\";\n    params.data_limit_bytes = 1000000; // 1 MB\n\n    try {\n        std::future\u003cstd::string\u003e createKeyFuture = client-\u003ecreateAccessKeyAsync(params);\n        std::string createdKey = createKeyFuture.get();\n        std::cout \u003c\u003c \"Created Access Key: \" \u003c\u003c createdKey \u003c\u003c std::endl;\n    } catch (const outline::OutlineServerErrorException\u0026 e) {\n        std::cerr \u003c\u003c \"Server Error: \" \u003c\u003c e.what() \u003c\u003c std::endl;\n    } catch (const outline::OutlineParseException\u0026 e) {\n        std::cerr \u003c\u003c \"Parse Error: \" \u003c\u003c e.what() \u003c\u003c std::endl;\n    } catch (const std::exception\u0026 e) {\n        std::cerr \u003c\u003c \"Unexpected Error: \" \u003c\u003c e.what() \u003c\u003c std::endl;\n    }\n\n    return 0;\n}\n```\n\n### Deleting an Access Key\n\nTo delete an existing access key by its ID:\n\n```cpp\nstd::string accessKeyId = \"your-access-key-id\";\n\ntry {\n    std::future\u003cvoid\u003e deleteKeyFuture = client-\u003edeleteAccessKeyAsync(accessKeyId);\n    deleteKeyFuture.get();\n    std::cout \u003c\u003c \"Access Key deleted successfully.\" \u003c\u003c std::endl;\n} catch (const outline::OutlineServerErrorException\u0026 e) {\n    std::cerr \u003c\u003c \"Server Error: \" \u003c\u003c e.what() \u003c\u003c std::endl;\n} catch (const std::exception\u0026 e) {\n    std::cerr \u003c\u003c \"Unexpected Error: \" \u003c\u003c e.what() \u003c\u003c std::endl;\n}\n```\n\n### Adding a Data Limit\n\nTo set a data usage limit for a specific access key:\n\n```cpp\nstd::string accessKeyId = \"your-access-key-id\";\nint dataLimitBytes = 5000000; // 5 MB\n\ntry {\n    std::future\u003cvoid\u003e addLimitFuture = client-\u003eaddDataLimitAsync(accessKeyId, dataLimitBytes);\n    addLimitFuture.get();\n    std::cout \u003c\u003c \"Data limit added successfully.\" \u003c\u003c std::endl;\n} catch (const outline::OutlineServerErrorException\u0026 e) {\n    std::cerr \u003c\u003c \"Server Error: \" \u003c\u003c e.what() \u003c\u003c std::endl;\n} catch (const std::exception\u0026 e) {\n    std::cerr \u003c\u003c \"Unexpected Error: \" \u003c\u003c e.what() \u003c\u003c std::endl;\n}\n```\n\n### Retrieving Access Keys\n\nTo retrieve all access keys:\n\n```cpp\ntry {\n    std::future\u003cstd::string\u003e accessKeysFuture = client-\u003egetAccessKeysAsync();\n    std::string accessKeys = accessKeysFuture.get();\n    std::cout \u003c\u003c \"Access Keys: \" \u003c\u003c accessKeys \u003c\u003c std::endl;\n} catch (const outline::OutlineServerErrorException\u0026 e) {\n    std::cerr \u003c\u003c \"Server Error: \" \u003c\u003c e.what() \u003c\u003c std::endl;\n} catch (const outline::OutlineParseException\u0026 e) {\n    std::cerr \u003c\u003c \"Parse Error: \" \u003c\u003c e.what() \u003c\u003c std::endl;\n} catch (const std::exception\u0026 e) {\n    std::cerr \u003c\u003c \"Unexpected Error: \" \u003c\u003c e.what() \u003c\u003c std::endl;\n}\n```\n\n### Managing Server Metrics\n\n#### Enabling Metrics\n\nMetrics provide insights into server performance and usage statistics. To enable metrics:\n\n```cpp\nbool enable = true;\n\ntry {\n    std::future\u003cvoid\u003e setMetricsFuture = client-\u003esetMetricsStatusAsync(enable);\n    setMetricsFuture.get();\n    std::cout \u003c\u003c \"Metrics enabled successfully.\" \u003c\u003c std::endl;\n} catch (const outline::OutlineServerErrorException\u0026 e) {\n    std::cerr \u003c\u003c \"Server Error: \" \u003c\u003c e.what() \u003c\u003c std::endl;\n} catch (const std::exception\u0026 e) {\n    std::cerr \u003c\u003c \"Unexpected Error: \" \u003c\u003c e.what() \u003c\u003c std::endl;\n}\n```\n\n#### Retrieving Metrics\n\nTo retrieve current server metrics:\n\n```cpp\ntry {\n    std::future\u003cstd::string\u003e metricsFuture = client-\u003egetMetricsAsync();\n    std::string metrics = metricsFuture.get();\n    std::cout \u003c\u003c \"Server Metrics: \" \u003c\u003c metrics \u003c\u003c std::endl;\n} catch (const outline::OutlineServerErrorException\u0026 e) {\n    std::cerr \u003c\u003c \"Server Error: \" \u003c\u003c e.what() \u003c\u003c std::endl;\n} catch (const outline::OutlineParseException\u0026 e) {\n    std::cerr \u003c\u003c \"Parse Error: \" \u003c\u003c e.what() \u003c\u003c std::endl;\n} catch (const std::exception\u0026 e) {\n    std::cerr \u003c\u003c \"Unexpected Error: \" \u003c\u003c e.what() \u003c\u003c std::endl;\n}\n```\n\nTo enable the posibility for getting metrics and retrieve them:\n\n```cpp\n#include \"outline/OutlineClient.h\"\n#include \"outline/utils/UrlUtils.h\"\n\n#include \u003ciostream\u003e\n#include \u003cmemory\u003e\n\nint main() {\n    std::string apiUrl = \"https://your-outline-server.com/api\";\n    std::string cert = \"\"; // Add your server certificate if required\n    int timeout = 10;\n\n    auto client = outline::OutlineClient::create(apiUrl, cert, timeout);\n\n    try {\n        // Enable server metrics\n        bool enableMetrics = true;\n        std::future\u003cvoid\u003e enableFuture = client-\u003esetMetricsStatusAsync(enableMetrics);\n        enableFuture.get();\n        std::cout \u003c\u003c \"Server metrics enabled.\" \u003c\u003c std::endl;\n\n        // Retrieve server metrics\n        std::future\u003cstd::string\u003e metricsFuture = client-\u003egetMetricsAsync();\n        std::string metrics = metricsFuture.get();\n        std::cout \u003c\u003c \"Server Metrics: \" \u003c\u003c metrics \u003c\u003c std::endl;\n\n        // Interpret metrics (example output)\n        /*\n        {\n            \"activeConnections\": 5,\n            \"totalDataTransferred\": 1500000,\n            \"serverUptime\": 86400,\n            \"errorRate\": 0.01\n        }\n        */\n\n    } catch (const outline::OutlineServerErrorException\u0026 e) {\n        std::cerr \u003c\u003c \"Server Error: \" \u003c\u003c e.what() \u003c\u003c std::endl;\n    } catch (const outline::OutlineParseException\u0026 e) {\n        std::cerr \u003c\u003c \"Parse Error: \" \u003c\u003c e.what() \u003c\u003c std::endl;\n    } catch (const std::exception\u0026 e) {\n        std::cerr \u003c\u003c \"Unexpected Error: \" \u003c\u003c e.what() \u003c\u003c std::endl;\n    }\n\n    return 0;\n}\n```\n\n**Understanding Metrics:**\n\n- **Usage Statistics**: Data on bandwidth consumption.\n\nEnabling metrics makes it possible to retrieve them from server via API like it is shown in the previous example.\n\n### Configuring Server Settings\n\n#### Setting Server Name\n\nTo set or update the server's display name:\n\n```cpp\nstd::string serverName = \"My Outline Server\";\n\ntry {\n    std::future\u003cvoid\u003e setNameFuture = client-\u003esetServerNameAsync(serverName);\n    setNameFuture.get();\n    std::cout \u003c\u003c \"Server name set successfully.\" \u003c\u003c std::endl;\n} catch (const outline::OutlineServerErrorException\u0026 e) {\n    std::cerr \u003c\u003c \"Server Error: \" \u003c\u003c e.what() \u003c\u003c std::endl;\n} catch (const std::exception\u0026 e) {\n    std::cerr \u003c\u003c \"Unexpected Error: \" \u003c\u003c e.what() \u003c\u003c std::endl;\n}\n```\n\n#### Setting Hostname\n\nTo configure the server's hostname:\n\n```cpp\nstd::string hostName = \"vpn.example.com\";\n\ntry {\n    std::future\u003cvoid\u003e setHostFuture = client-\u003esetHostNameAsync(hostName);\n    setHostFuture.get();\n    std::cout \u003c\u003c \"Hostname set successfully.\" \u003c\u003c std::endl;\n} catch (const outline::OutlineServerErrorException\u0026 e) {\n    std::cerr \u003c\u003c \"Server Error: \" \u003c\u003c e.what() \u003c\u003c std::endl;\n} catch (const std::exception\u0026 e) {\n    std::cerr \u003c\u003c \"Unexpected Error: \" \u003c\u003c e.what() \u003c\u003c std::endl;\n}\n```\n\n#### Setting Default Port\n\nTo set the default port for new access keys:\n\n```cpp\nint defaultPort = 443;\n\ntry {\n    std::future\u003cvoid\u003e setPortFuture = client-\u003esetDefaultPortAsync(defaultPort);\n    setPortFuture.get();\n    std::cout \u003c\u003c \"Default port set successfully.\" \u003c\u003c std::endl;\n} catch (const outline::OutlineServerErrorException\u0026 e) {\n    std::cerr \u003c\u003c \"Server Error: \" \u003c\u003c e.what() \u003c\u003c std::endl;\n} catch (const std::exception\u0026 e) {\n    std::cerr \u003c\u003c \"Unexpected Error: \" \u003c\u003c e.what() \u003c\u003c std::endl;\n}\n```\n\n## API Reference\n\n### `OutlineClient` Class\n\n#### Constructor\n\n```cpp\nstatic std::shared_ptr\u003cOutlineClient\u003e create(std::string_view apiUrl, std::string_view cert, int timeout = 5);\n```\n\n- **Parameters**:\n  - `apiUrl`: The URL for the Outline server API.\n  - `cert`: Server certificate for SSL/TLS verification.\n  - `timeout`: Request timeout in seconds (default is 5 seconds).\n\n#### Synchronous Methods\n\nFor convenience, the library also provides synchronous versions of the asynchronous methods. These methods block until the operation completes.\n\n## Contributing\n\nContributions are welcome! If you'd like to improve the library, please follow these steps:\n\n1. **Fork the Repository**\n\n2. **Create a New Branch**\n\n   ```bash\n   git checkout -b feature/YourFeatureName\n   ```\n\n3. **Make Your Changes**\n\n4. **Commit Your Changes**\n\n   ```bash\n   git commit -m \"Add your commit message\"\n   ```\n\n5. **Push to Your Fork**\n\n   ```bash\n   git push origin feature/YourFeatureName\n   ```\n\n6. **Create a Pull Request**\n\n   Describe your changes and why they are beneficial.\n\n## License\n\nThis project is licensed under the [MIT License](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flinkartemy%2Foutline-vpn-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flinkartemy%2Foutline-vpn-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flinkartemy%2Foutline-vpn-api/lists"}