{"id":26093872,"url":"https://github.com/ngrok/ngrok-api-java","last_synced_at":"2025-04-12T08:43:00.426Z","repository":{"id":40574252,"uuid":"374431019","full_name":"ngrok/ngrok-api-java","owner":"ngrok","description":"ngrok API client library for Java","archived":false,"fork":false,"pushed_at":"2024-07-30T17:15:23.000Z","size":2106,"stargazers_count":22,"open_issues_count":0,"forks_count":4,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-07-30T18:56:22.020Z","etag":null,"topics":["developer-tools","java","library","ngrok-client"],"latest_commit_sha":null,"homepage":"https://ngrok.com","language":"Java","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/ngrok.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":"2021-06-06T18:08:20.000Z","updated_at":"2024-07-30T15:02:25.000Z","dependencies_parsed_at":"2024-04-30T21:45:35.186Z","dependency_job_id":"56c69c9a-3056-47b8-bf49-e7b09004ff4c","html_url":"https://github.com/ngrok/ngrok-api-java","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ngrok%2Fngrok-api-java","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ngrok%2Fngrok-api-java/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ngrok%2Fngrok-api-java/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ngrok%2Fngrok-api-java/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ngrok","download_url":"https://codeload.github.com/ngrok/ngrok-api-java/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248543705,"owners_count":21121836,"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":["developer-tools","java","library","ngrok-client"],"created_at":"2025-03-09T12:05:58.495Z","updated_at":"2025-04-12T08:43:00.407Z","avatar_url":"https://github.com/ngrok.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!-- Code generated for API Clients. DO NOT EDIT. --\u003e\n\n# Unstable\n\nThis library is currently unstable. We know of rough edges\nand are working to bring it to parity with our other API client\nlibraries. Please feel free to try it out and let us know if you find\nit useful!\n\n# ngrok API client library for Java\n\nThis library wraps the [ngrok HTTP API](https://ngrok.com/docs/api) to\nmake it easier to consume in Java.\n\n## Usage\n\nThis library is published on [Maven\nCentral](https://search.maven.org/artifact/com.ngrok/ngrok-api-java).\n\nIn your Maven `pom.xml` file, add:\n\n```xml\n\u003cdependencies\u003e\n  \u003cdependency\u003e\n    \u003cgroupId\u003ecom.ngrok\u003c/groupId\u003e\n    \u003cartifactId\u003engrok-api-java\u003c/artifactId\u003e\n    \u003cversion\u003e${ngrok-api-java.version}\u003c/version\u003e\n  \u003c/dependency\u003e\n\u003c/dependencies\u003e\n```\n\nSee the above URL for the latest version of the API client.\n\n## Support\n\nThe best place to get support using this library is through the [ngrok Slack Community](https://ngrok.com/slack). If you find any bugs, please contribute by opening a [new GitHub issue](https://github.com/ngrok/ngrok-api-java/issues/new/choose).\n\n## Documentation\n\nAll objects, methods and properties are documented with Javadoc for\nintegration with an IDE like IntelliJ IDEA or Eclipse. You can also\n[view the documentation online](https://java-api.docs.ngrok.com/).\n\nBeyond that, this readme is the best source of documentation for the\nlibrary.\n\n### Versioning\n\nThis class library is published to Maven Central using semantic\nversioning. Breaking changes to the API will only be released with a\nbump of the major version number. Each released commit is tagged in\nthis repository.\n\nNo compatibility promises are made for versions \u003c 1.0.0.\n\n### Quickstart\n\nFirst, use the ngrok dashboard to generate an API key. Store that in a\nsafe place. Inject it into your application using the environment\nvariable `NGROK_API_KEY`. The `Ngrok.createDefault()` method will pull\nfrom that environment variable. If you prefer, you can also pass the API\nkey explicitly.\n\n#### Create an IP Policy that allows traffic from some subnets\n\n```java\nimport com.ngrok.*;\n\nimport java.util.concurrent.CompletableFuture;\nimport java.util.stream.Stream;\n\npublic class Example {\n    public static void main(final String[] args) {\n        final var ngrok = Ngrok.createDefault();\n\n        ngrok.ipPolicies().create().call().thenCompose(policy -\u003e\n            CompletableFuture.allOf(\n                Stream.of(\"24.0.0.0/8\", \"12.0.0.0/8\")\n                    .map(cidr -\u003e\n                        ngrok.ipPolicyRules()\n                            .create(cidr, policy.getId(), \"allow\")\n                            .call()\n                            .toCompletableFuture()\n                    )\n                    .toArray(CompletableFuture[]::new)\n            )\n        ).toCompletableFuture().join();\n    }\n}\n```\n\n#### List all online tunnels\n\n```java\nimport com.ngrok.*;\nimport com.ngrok.definitions.*;\n\nimport java.util.concurrent.CompletableFuture;\nimport java.util.concurrent.CompletionStage;\n\npublic class Example {\n    public static void main(final String[] args) {\n        final var ngrok = Ngrok.createDefault();\n\n        System.out.println(\"Tunnels:\");\n        ngrok.tunnels().list().call()\n            .thenCompose(tunnelPage -\u003e printRecursively(ngrok, tunnelPage))\n            .toCompletableFuture().join();\n    }\n\n    private static CompletionStage\u003cVoid\u003e printRecursively(final Ngrok ngrok, final Page\u003cTunnelList\u003e currentPage) {\n        currentPage.getPage().getTunnels.forEach(System.out::println);\n        return currentPage.next().thenCompose(maybeTunnelPage -\u003e maybeTunnelPage\n            .map(tunnelPage -\u003e printRecursively(ngrok, tunnelPage))\n            .orElseGet(() -\u003e CompletableFuture.\u003cVoid\u003ecompletedFuture(null))\n        );\n    }\n}\n```\n\n### Conventions\n\nConventional usage of this package is to construct a root `Ngrok` object\nusing the static `createDefault()` method. You can then access API\nresources using that object. Do not construct the individual API\nresource client classes in your application code.\n\nYou can also customize low-level behavior by instantiating the\n`DefaultNgrokApiClient` yourself, and then using it to construct the\n`Ngrok` instance. If you'd like to use a different HTTP library\nentirely, you can even implement the `NgrokApiClient` interface\nyourself.\n\n```java\nimport com.ngrok.*;\n\npublic class Example {\n    public static void main(final String[] args) {\n        // Create the root api client using an API key from the environment variable NGROK_API_KEY\n        final var defaultNgrok = Ngrok.createDefault();\n\n        // ... or create the root api client using an API key provided directly\n        final var defaultNgrokWithApiKey = Ngrok.createDefault(\"my secret api key\");\n\n        // ... or create the root api client by customizing the low-level networking details\n        final var customApiClient = DefaultNgrokApiClient\n            .newBuilder(System.getenv(\"NGROK_API_KEY\"))\n            .ojectMapper(new ObjectMapper().registerModule(new JavaTimeModule()).registerModule(new Jdk8Module()))\n            .baseUri(URI.create(\"https://some-other-server.com\"))\n            .build();\n        final var ngrokWithCustomApiClient = new Ngrok(customApiClient);\n\n        // Clients for all api resources (like ip policies) are acccessible via methods on the root client\n        final var policy = defaultNgrok.ipPolicies()\n            .get(policyId)\n            .call().toCompletableFuture().join();\n\n        // Some api resources are 'namespaced' through another method\n        final var circuitBreaker = defaultNgrok.pointcfgModule()\n            .circuitBreaker()\n            .get(endpointConfigId).call()\n            .toCompletableFuture().join();\n    }\n}\n```\n\n### Paging\n\nAll list responses from the ngrok API are paged. All list response\nobjects implement the `Pageable` interface, and are wrapped in a `Page`\nclass, which has a `next()` method. Calling `next()` will asyncronously\nrequest the next page. If no next page is available, an empty `Optional`\nwill be returned inside the `CompletionStage`.\n\n```java\nimport com.ngrok.*;\nimport com.ngrok.definitions.*;\n\nimport java.util.concurrent.CompletableFuture;\nimport java.util.concurrent.CompletionStage;\n\npublic class Example {\n    public static void main(final String[] args) {\n        final var ngrok = Ngrok.createDefault();\n\n        ngrok.credentials().list().call()\n            .thenCompose(credentialPage -\u003e printRecursively(ngrok, credentiasPage))\n            .toCompletableFuture().join();\n    }\n\n    private static CompletionStage\u003cVoid\u003e printRecursively(final Ngrok ngrok, final Page\u003cCredentialList\u003e currentPage) {\n        currentPage.getPage().getTunnels.forEach(System.out::println);\n        return currentPage.next().thenCompose(maybeCredentialPage -\u003e maybeCredentialPage\n            .map(credentialPage -\u003e printRecursively(ngrok, credentialPage))\n            .orElseGet(() -\u003e CompletableFuture.\u003cVoid\u003ecompletedFuture(null))\n        );\n    }\n}\n```\n\n### Error Handling\n\nAll errors returned by the ngrok API are serialized as structured\npayloads for easy error handling. If a structured error is returned by\nthe ngrok API, this library will return a failed `CompletionStage`\ncontaining a `NgrokApiError`.\n\nThis object will allow you to check the unique ngrok error code and the\nhttp status code of a failed response. Use the `getErrorCode()` method\nto check for unique ngrok error codes returned by the API. All error\ncodes are documented at\n[https://ngrok.com/docs/errors](https://ngrok.com/docs/errors). There is\nalso an `isErrorCode()` method on the exception object to check against\nmultiple error codes. The `getHttpStatusCode()` method can be used to\ncheck not found errors.\n\nOther non-structured errors encountered while making an API call from\ne.g. networking or serialization failures are not wrapped in any way and\nwill bubble up as normal.\n\n```java\nimport com.ngrok.*;\nimport com.ngrok.definitions.*;\n\npublic class Example {\n    public static void main(final String[] args) {\n        final var ngrok = Ngrok.createDefault();\n\n        ngrok.reservedDomains().create(System.getenv(\"NGROK_DOMAIN\"))\n            .description(\"example domain\")\n            .call()\n            .whenComplete((domain, error) -\u003e {\n                if (error != null) {\n                    if (error instanceof NgrokApiError ngrokError) {\n                        if (ngrokError.isErrorCode(\"NGROK_ERR_402\", \"NGROK_ERR_403\")) {\n                            System.out.println(\"Ignoring invalid wildcard domain.\");\n                        } else {\n                            System.out.printf(\"API Error (%s): %s%n\", ngrokError.getErrorCode().orElse(\"\"), ngrokError.getMessage());\n                        }\n                    } else {\n                        System.out.println(\"Other error: \" + error.getMessage());\n                    }\n                } else {\n                    System.out.println(\"Successfully reserved domain\");\n                }\n            })\n            .toCompletableFuture().join();\n    }\n}\n```\n\n### Datatype Overrides\n\nAll datatype objects in the ngrok API library properly override\n`equals()` and `hashCode()` so that the objects can be compared.\nSimilarly, they override `toString()` for more helpful pretty printing\nof ngrok domain objects.\n\n### Sync / Async Interfaces\n\nThe `call()` method on each API client operation is asynchronous and\nreturns a `CompletionStage`. If you require a synchronous call, you can\nuse `blockingCall()` instead.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fngrok%2Fngrok-api-java","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fngrok%2Fngrok-api-java","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fngrok%2Fngrok-api-java/lists"}