{"id":28829294,"url":"https://github.com/ballerina-platform/module-ballerina-http","last_synced_at":"2026-04-10T08:02:38.750Z","repository":{"id":36950236,"uuid":"288615161","full_name":"ballerina-platform/module-ballerina-http","owner":"ballerina-platform","description":"Ballerina HTTP Module","archived":false,"fork":false,"pushed_at":"2025-06-18T09:55:12.000Z","size":56969,"stargazers_count":124,"open_issues_count":1,"forks_count":89,"subscribers_count":69,"default_branch":"master","last_synced_at":"2025-06-18T10:49:01.566Z","etag":null,"topics":["ballerina","hacktoberfest","http","http-client","http-server","http2","integration","rest","websocket","wso2"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":false,"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/ballerina-platform.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":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2020-08-19T02:37:49.000Z","updated_at":"2025-06-18T09:55:17.000Z","dependencies_parsed_at":"2024-01-11T04:38:27.269Z","dependency_job_id":"78f42b90-04b3-4684-829e-671a6a9e7fa5","html_url":"https://github.com/ballerina-platform/module-ballerina-http","commit_stats":null,"previous_names":[],"tags_count":129,"template":false,"template_full_name":null,"purl":"pkg:github/ballerina-platform/module-ballerina-http","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ballerina-platform%2Fmodule-ballerina-http","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ballerina-platform%2Fmodule-ballerina-http/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ballerina-platform%2Fmodule-ballerina-http/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ballerina-platform%2Fmodule-ballerina-http/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ballerina-platform","download_url":"https://codeload.github.com/ballerina-platform/module-ballerina-http/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ballerina-platform%2Fmodule-ballerina-http/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260690958,"owners_count":23047106,"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":["ballerina","hacktoberfest","http","http-client","http-server","http2","integration","rest","websocket","wso2"],"created_at":"2025-06-19T05:12:44.692Z","updated_at":"2026-04-10T08:02:38.744Z","avatar_url":"https://github.com/ballerina-platform.png","language":"Java","funding_links":[],"categories":["网络编程"],"sub_categories":["Spring Cloud框架"],"readme":"Ballerina HTTP Library\n===================\n\n  [![Build](https://github.com/ballerina-platform/module-ballerina-http/actions/workflows/build-timestamped-master.yml/badge.svg)](https://github.com/ballerina-platform/module-ballerina-http/actions/workflows/build-timestamped-master.yml)\n  [![codecov](https://codecov.io/gh/ballerina-platform/module-ballerina-http/branch/master/graph/badge.svg)](https://codecov.io/gh/ballerina-platform/module-ballerina-http)\n  [![Trivy](https://github.com/ballerina-platform/module-ballerina-http/actions/workflows/trivy-scan.yml/badge.svg)](https://github.com/ballerina-platform/module-ballerina-http/actions/workflows/trivy-scan.yml)\n  [![GraalVM Check](https://github.com/ballerina-platform/module-ballerina-http/actions/workflows/build-with-bal-test-graalvm.yml/badge.svg)](https://github.com/ballerina-platform/module-ballerina-http/actions/workflows/build-with-bal-test-graalvm.yml)\n  [![GitHub Last Commit](https://img.shields.io/github/last-commit/ballerina-platform/module-ballerina-http.svg)](https://github.com/ballerina-platform/module-ballerina-http/commits/master)\n  [![Github issues](https://img.shields.io/github/issues/ballerina-platform/ballerina-standard-library/module/http.svg?label=Open%20Issues)](https://github.com/ballerina-platform/ballerina-standard-library/labels/module%2Fhttp)\n\nThis library provides APIs for connecting and interacting with HTTP and HTTP2 endpoints. It\nfacilitates two types of network entry points as the `Client` and `Listener`.\n\n### Client\n\nThe `Client` is used to connect to and interact with HTTP endpoints. They support connection pooling and can be\nconfigured to have a maximum number of active connections that can be made with the remote endpoint. The `Client`\nactivates connection eviction after a given idle period and also supports follow-redirects so that you do not\nhave to manually handle 3xx HTTP status codes.\n\n#### Resiliency\n\nThe `Client` handles resilience in multiple ways such as load balancing, circuit breaking, endpoint timeouts, and via a\nretry mechanism.\n\nLoad balancing is used in the round-robin or failover manner.\n\nWhen a failure occurs in the remote service, the client connections might wait for some time before a timeout occurs.\nAwaiting requests consume resources in the system. Circuit Breakers are used to trip after a certain number of failed\nrequests to the remote service. Once a circuit breaker trips, it does not allow the client to send requests to the\nremote service for a period of time.\n\nThe Ballerina circuit breaker supports tripping on HTTP error status codes and I/O errors. Failure thresholds can be\nconfigured based on a sliding window (e.g., 5 failures within 10 seconds). The `Client` also supports a retry\nmechanism that allows it to resend failed requests periodically for a given number of times.\n\n#### Security\n\nThe `Client` supports Server Name Indication (SNI), Certificate Revocation List (CRL), Online Certificate Status\nProtocol (OCSP), and OCSP Stapling for SSL/TLS connections.\nAlso, the `Client` can be configured to send authentication information to the endpoint being invoked. Ballerina has\nbuilt-in support for Basic authentication, JWT authentication, and OAuth2 authentication.\n\nIn addition to that, it supports both HTTP/1.1 and HTTP2 protocols and connection keep-alive, content\nchunking, HTTP caching, data compression/decompression, response payload binding, and authorization can be highlighted as the features of the `Clients`.\n\nA `Client` can be defined using the URL of the remote service that it needs to connect with as shown below:\n\n```ballerina\nhttp:Client clientEndpoint = check new(\"https://my-simple-backend.com\");\n```\nThe defined `Client` endpoint can be used to call a remote service as follows:\n\n```ballerina\n// Send a GET request to the specified endpoint.\nhttp:Response response = check clientEndpoint-\u003e/backend(id = 123);\n```\nThe payload can be retrieved as the return value from the remote function as follows:\n\n```ballerina\n// Retrieve payload as json.\njson payload = check clientEndpoint-\u003e/backend/Json.post(\"foo\");\n```\n\n### Listener\n\nThe `Listener` is the underneath server connector that binds the given IP/Port to the network and it's behavior can\nbe changed using the `http:ListenerConfiguration`. In HTTP, the `http:Service`-typed services can be attached to\nthe `Listener`. The service type precisely describes the syntax for both the service and resource.\n\nA `Service` represents a collection of network-accessible entry points and can be exposed via a `Listener` endpoint.\nA resource represents one such entry point and can have its own path, HTTP methods, body format, `consumes` and\n`produces` content types, CORS headers, etc. In resources, the HTTP method and resource path are mandatory parameters and\nthe String literal and path parameters can be stated as the path. The resource method accepts the `http:Caller`, `http:Request`,\n`http:Headers`, query parameters, header parameters, and payload parameters as arguments. However, they are optional.\n\nWhen a `Service` receives a request, it is dispatched to the best-matched resource.\n\nA `Listener` endpoint can be defined as follows:\n\n```ballerina\n// Attributes associated with the `Listener` endpoint are defined here.\nlistener http:Listener helloWorldEP = new(9090);\n```\n\nThen a `Service` can be defined and attached to the above `Listener` endpoint as shown below:\n\n```ballerina\n// By default, Ballerina assumes that the service is to be exposed via HTTP/1.1.\nservice /helloWorld on helloWorldEP {\n\n   resource function post [string name](@http:Payload string message) returns string {\n       // Sends the response back to the client along with a string payload.\n       return \"Hello, World! I’m \" + name + \". \" + message;\n   }\n}\n```\n\n#### Security\n\n`Listener` endpoints can be exposed via SSL. They support Mutual SSL, Hostname Verification, and Application Layer\nProtocol Negotiation (ALPN) for HTTP2. `Listener` endpoints also support Certificate Revocation List (CRL), Online\nCertificate Status Protocol (OCSP), and OCSP Stapling.\nAlso, The `listener` can be configured to authenticate and authorize the inbound requests. Ballerina has\nbuilt-in support for basic authentication, JWT authentication, and OAuth2 authentication.\n\nIn addition to that, supports both the HTTP/1.1 and HTTP2 protocols and connection keep-alive, content\nchunking, HTTP caching, data compression/decompression, payload binding, and authorization can be highlighted as the features of a `Service`.\n\n## Issues and projects \n\nIssues and Projects tabs are disabled for this repository as this is part of the Ballerina Standard Library. To report bugs, request new features, start new discussions, view project boards, etc. please visit Ballerina Standard Library [parent repository](https://github.com/ballerina-platform/ballerina-standard-library). \n\nThis repository only contains the source code for the package.\n\n## Build from the source\n\n### Set Up the prerequisites\n\n1. Download and install Java SE Development Kit (JDK) version 21 (from one of the following locations).\n\n   * [Oracle](https://www.oracle.com/java/technologies/downloads/)\n   \n   * [OpenJDK](https://adoptium.net/)\n   \n        \u003e **Note:** Set the JAVA_HOME environment variable to the path name of the directory into which you installed JDK.\n\n2. Export GitHub Personal access token with read package permissions as follows,\n\n        export packageUser=\u003cUsername\u003e\n        export packagePAT=\u003cPersonal access token\u003e\n\n3. Download and install [Docker](https://www.docker.com/) and Docker Compose.\n\n### Build the source\n\nExecute the commands below to build from source.\n\n1. To build the library:\n    ```\n    ./gradlew clean build\n    ```\n   \n2. To run the integration tests:\n    ```\n    ./gradlew clean test\n    ```\n\n3. To run a group of tests\n    ```\n    ./gradlew clean test -Pgroups=\u003ctest_group_names\u003e\n    ```\n\n4. To build the package without the tests:\n    ```\n    ./gradlew clean build -x test\n    ```\n   \n5. To debug the tests:\n    ```\n    ./gradlew clean test -Pdebug=\u003cport\u003e\n    ```\n   \n6. To debug with Ballerina language:\n    ```\n    ./gradlew clean build -PbalJavaDebug=\u003cport\u003e\n    ```\n\n7. Publish the generated artifacts to the local Ballerina central repository:\n    ```\n    ./gradlew clean build -PpublishToLocalCentral=true\n    ```\n\n8. Publish the generated artifacts to the Ballerina central repository:\n    ```\n    ./gradlew clean build -PpublishToCentral=true\n    ```\n\n## Contribute to Ballerina\n\nAs an open source project, Ballerina welcomes contributions from the community. \n\nFor more information, go to the [contribution guidelines](https://github.com/ballerina-platform/ballerina-lang/blob/master/CONTRIBUTING.md).\n\n## Code of conduct\n\nAll contributors are encouraged to read the [Ballerina Code of Conduct](https://ballerina.io/code-of-conduct).\n\n## Useful links\n\n* For more information go to the [`HTTP` library](https://lib.ballerina.io/ballerina/http/latest).\n* For example demonstrations of the usage, go to [Ballerina By Examples](https://ballerina.io/learn/by-example/).\n* Chat live with us via our [Discord server](https://discord.gg/ballerinalang).\n* Post all technical questions on Stack Overflow with the [#ballerina](https://stackoverflow.com/questions/tagged/ballerina) tag.\n* View the [Ballerina performance test results](https://github.com/ballerina-platform/ballerina-lang/blob/master/performance/benchmarks/summary.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fballerina-platform%2Fmodule-ballerina-http","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fballerina-platform%2Fmodule-ballerina-http","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fballerina-platform%2Fmodule-ballerina-http/lists"}