{"id":42643209,"url":"https://github.com/datatrails/go-datatrails-common-api","last_synced_at":"2026-01-29T06:34:32.392Z","repository":{"id":196683621,"uuid":"696797531","full_name":"datatrails/go-datatrails-common-api","owner":"datatrails","description":"Common public api definitions for the DataTrails platform","archived":false,"fork":false,"pushed_at":"2025-04-24T12:57:17.000Z","size":194,"stargazers_count":0,"open_issues_count":2,"forks_count":0,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-04-24T13:43:52.974Z","etag":null,"topics":[],"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/datatrails.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,"zenodo":null}},"created_at":"2023-09-26T13:02:13.000Z","updated_at":"2025-04-16T16:31:23.000Z","dependencies_parsed_at":null,"dependency_job_id":"ac1a9b8e-7e65-461a-844a-b5f33b2f9733","html_url":"https://github.com/datatrails/go-datatrails-common-api","commit_stats":null,"previous_names":["rkvst/rkvstcommon-api","datatrails/datatrails-common-api","datatrails/go-datatrails-common-api"],"tags_count":45,"template":false,"template_full_name":null,"purl":"pkg:github/datatrails/go-datatrails-common-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datatrails%2Fgo-datatrails-common-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datatrails%2Fgo-datatrails-common-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datatrails%2Fgo-datatrails-common-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datatrails%2Fgo-datatrails-common-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/datatrails","download_url":"https://codeload.github.com/datatrails/go-datatrails-common-api/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datatrails%2Fgo-datatrails-common-api/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28867104,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-29T05:56:06.453Z","status":"ssl_error","status_checked_at":"2026-01-29T05:55:57.668Z","response_time":59,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":[],"created_at":"2026-01-29T06:34:31.737Z","updated_at":"2026-01-29T06:34:32.385Z","avatar_url":"https://github.com/datatrails.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# go-datatrails-common-api\n\nCommon public api definitions for the DataTrails platform\n\n## Finding and including proto files for depdendecnies\n\ntools/go.mod is the source of truth for all proto providing dependencies. That file alone specifies both the upstream version we are using *and* is used, via go install, to make the .proto files available locally\n\nThis corresponds to the practice recommended by grpc-gateway and elsewhere\n\n1. *** ALWAYS *** Use tools/go.mod to specify the dependency version.\n2. Add the package to the `go install` command in the apis:preflight task\n3. If necessary, add a var for the new path in any-api **and** then add a reference to that var in the PROTO_INC var.\n\nFollowing this practice removes the need for dual maintenance of dependency versions in the builder image. It also produces a build cycle that is significantly faster.\n\nCross repository builds in docker while using go.work to refer to locally modified sources don't work. And this setup is essential for an efficient workflow.\n\n## bootstrap proto files\n\nThe proto's for protoc itself, the googleapis, and the grpc_health proxy are needed by almost everything and are also don't apear to be compatible with the tools/go.mod approach\n\nFor this reason we curl the proto's and make them available in our aggregate proto-includes archive\n\n## Workflow for updating common apis\n\n### Ensure the go tool chain is setup on your host\n\nIt is inordinately cumbersome to set this all up for docker. It can't be\nachieved without imposing significant inneficiencies in the workflow. For any\nengineer working on the api's it is reasonable to expect they can install the\ncorrect version of go for their host, and likely already have.\n\n### Use an avid/src/go.work\n\nFirst point avid at a clone of this repo so that it's imports will resolve\ndirectly against the sources in `./api`\n\n### Familiarize with the workflow sub tasks\n\nThe general use entry points all use Docker and do not support efficiently and\niteratively developing avid and other dependents against a local clone of this\nrepo.\n\n#### For this repo\n\nYou can do everything in the builder image using `task all`. This uses the\nblessed builder image and requires no host setup other than docker.\n\nIf you are iterating it is a lot more efficient to use the sub tasks, because they all run on your host.\n\n`task` `apis:bootstrap` -\u003e `task:apis:generate` -\u003e `task:apis:test` -\u003e `task:apis:export`\n\nThe source of truth for the host build is .github/workflows/ci.yml as that is\nhow the CI pipeline works. It does not use our builder image.\n\n| Command                        | When                            |\n| ---------------------          | ------------------------------: |\n| `task apis:bootstrap`          | once after clone or rebase      |\n| `task apis:clean:generated`    | once after clone or rebase      |\n| `task apis:generate`           | every time the .proto changes   |\n| `task apis:test`               | every time the .proto changes   |\n| `task apis:export`             | every time the .proto changes   |\n\nIf you want to iterate on *just* the helper go code and there tests, do one round of\n\n`apis:bootstrap` -\u003e `apis:clean:generated`\n\nThen just iterate using `task apis:generate` and `task apis:test`\n\n#### For avid\n\nSee the README.md in avid/src/api/README.md\n\n##### Build one api against locally cloned go-datatrails-common-api\n\nThe protos can be included exactly as they are found from a clone of go-datatrails-common-api. *Without* needing to generate, build or export. Eg,\n\n    task apis:assetsv2-api \\\n        DATATRAILS_COMMON_API=\"../../go-datatrails-common-api\"\n\nIt is necessary however to run `task apis:bootsrap` after cloning go-datatrails-common\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdatatrails%2Fgo-datatrails-common-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdatatrails%2Fgo-datatrails-common-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdatatrails%2Fgo-datatrails-common-api/lists"}