{"id":20958790,"url":"https://github.com/reubenmiller/go-c8y","last_synced_at":"2025-05-14T06:32:34.030Z","repository":{"id":38984130,"uuid":"157860483","full_name":"reubenmiller/go-c8y","owner":"reubenmiller","description":"Unofficial Go client for Cumulocity","archived":false,"fork":false,"pushed_at":"2025-04-17T12:59:22.000Z","size":4003,"stargazers_count":2,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-14T02:43:35.082Z","etag":null,"topics":["iot"],"latest_commit_sha":null,"homepage":"","language":"Go","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/reubenmiller.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,"zenodo":null}},"created_at":"2018-11-16T11:49:24.000Z","updated_at":"2025-04-17T12:58:28.000Z","dependencies_parsed_at":"2024-04-24T20:35:53.351Z","dependency_job_id":"773e670a-e268-45a2-b448-feec3819041a","html_url":"https://github.com/reubenmiller/go-c8y","commit_stats":null,"previous_names":[],"tags_count":176,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reubenmiller%2Fgo-c8y","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reubenmiller%2Fgo-c8y/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reubenmiller%2Fgo-c8y/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reubenmiller%2Fgo-c8y/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/reubenmiller","download_url":"https://codeload.github.com/reubenmiller/go-c8y/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254084718,"owners_count":22011932,"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":["iot"],"created_at":"2024-11-19T01:49:31.859Z","updated_at":"2025-05-14T06:32:29.016Z","avatar_url":"https://github.com/reubenmiller.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# go-c8y\n\nUnofficial Go client for [Cumulocity IoT](https://cumulocity.com/api/core/).\n\n[![tests](https://github.com/reubenmiller/go-c8y/actions/workflows/main.yml/badge.svg)](https://github.com/reubenmiller/go-c8y/actions/workflows/main.yml)\n[![Go Report Card](https://goreportcard.com/badge/github.com/reubenmiller/go-c8y)](https://goreportcard.com/report/github.com/reubenmiller/go-c8y)\n[![Documentation c8y](https://godoc.org/github.com/reubenmiller/go-c8y/pkg/c8y?status.svg)](https://godoc.org/github.com/reubenmiller/go-c8y/pkg/c8y)\n[![Documentation microservice ](https://godoc.org/github.com/reubenmiller/go-c8y/pkg/microservice?status.svg)](https://godoc.org/github.com/reubenmiller/go-c8y/pkg/microservice)\n\n## Caveats\n\nWe encourage you to try the package in your projects, just keep these caveats in mind, please:\n\n* **This is a work in progress.** Not all of the Cumulocity IoT REST API is covered, and the HTTP client is very simple. In the future the HTTP Client will be improved to support retries on failures, client side rate limiting, prometheus api metrics, mqtt client.\n\n* **There are no guarantees on API stability.** The general mechanics of the golang API are still being worked out. The balance between helpers and clarity is still being found. Given limited access to all available Cumulocity IoT versions, compatibility to all Cumulocity IoT versions is not guaranteed, however since Cumulocity IoT takes an additive approach to new features, it is more likely that the new features will be missing rather than existing API breaking (excluding deprecated features)\n\n## Usage\n\n1. Add the package to your project using `go get`:\n\n    ```sh\n    go get -u github.com/reubenmiller/go-c8y/c8y\n    ```\n\n1. Create a `main.go` file with the following\n\n    ```golang\n    package main\n\n    import (\n        \"context\"\n        \"log\"\n\n        \"github.com/reubenmiller/go-c8y/pkg/c8y\"\n    )\n\n    func main() {\n        // Create the client from the following environment variables\n        // C8Y_HOST, C8Y_TENANT, C8Y_USER, C8Y_PASSWORD\n        client := c8y.NewClientFromEnvironment(nil, false)\n\n        // Get list of alarms with MAJOR Severity\n        alarmCollection, _, err := client.Alarm.GetAlarms(\n            context.Background(),\n            \u0026c8y.AlarmCollectionOptions{\n                Severity: \"MAJOR\",\n            },\n        )\n\n        // Always check for errors\n        if err != nil {\n            log.Fatalf(\"Could not retrieve alarms. %s\", err)\n        }\n\n        log.Printf(\"Total alarms: %d\", len(alarmCollection.Alarms))\n    }\n    ```\n\n2. Set the credentials via environment variables\n\n    **Windows (PowerShell)**\n\n    ```sh\n    $env:C8Y_HOST = \"https://cumulocity.com\"\n    $env:C8Y_TENANT = \"mycompany\"\n    $env:C8Y_USER = \"username\"\n    $env:C8Y_PASSWORD = \"password\"\n    ```\n\n    **Linux/MacOS**\n\n    ```sh\n    export C8Y_HOST=https://cumulocity.com\n    export C8Y_TENANT=mycompany\n    export C8Y_USER=username\n    export C8Y_PASSWORD=password\n    ```\n\n3. Run the application\n\n    ```sh\n    go run main.go\n    ```\n\n## Examples\n\nMore examples can be found under the `examples` folder.\n\n## Development\n\n### Running the tests\n\nTo run the tests you will need to install [go-task](https://taskfile.dev/installation/), or use the dev container which includes go-task.\n\n1. Create a dotenv file `.env` to the root folder and add your Cumulocity credentials to use for the tests\n\n    ```sh\n    C8Y_HOST=https://cumulocity.com\n    C8Y_TENANT=mycompany\n    C8Y_USER=username\n    C8Y_PASSWORD=password\n    ```\n\n2. Execute the tests\n\n    ```sh\n    task test\n    ```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Freubenmiller%2Fgo-c8y","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Freubenmiller%2Fgo-c8y","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Freubenmiller%2Fgo-c8y/lists"}