{"id":21523829,"url":"https://github.com/bhojpur/api","last_synced_at":"2025-03-17T17:45:24.807Z","repository":{"id":38209663,"uuid":"459870042","full_name":"bhojpur/api","owner":"bhojpur","description":"The Bhojpur API is a web standards compliant, application programming interface for the Bhojpur.NET Platform ecosystem services.","archived":false,"fork":false,"pushed_at":"2023-01-01T14:01:07.000Z","size":486,"stargazers_count":0,"open_issues_count":2,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-01-24T05:11:18.458Z","etag":null,"topics":["api","go","golang","web"],"latest_commit_sha":null,"homepage":"https://page.bhojpur-consulting.com/product/api/","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bhojpur.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-02-16T05:51:21.000Z","updated_at":"2022-09-26T00:43:19.000Z","dependencies_parsed_at":"2023-01-31T23:01:02.871Z","dependency_job_id":null,"html_url":"https://github.com/bhojpur/api","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bhojpur%2Fapi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bhojpur%2Fapi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bhojpur%2Fapi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bhojpur%2Fapi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bhojpur","download_url":"https://codeload.github.com/bhojpur/api/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244082145,"owners_count":20395219,"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":["api","go","golang","web"],"created_at":"2024-11-24T01:19:30.922Z","updated_at":"2025-03-17T17:45:24.785Z","avatar_url":"https://github.com/bhojpur.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Bhojpur API - Platform Access Library\n\nThe Bhojpur API is a standard `client-side` library for accessing the `server-side` of\nthe [Bhojpur.NET Platform](https://github.com/bhojpur/platform) ecosystem. It offers a\ncomprehensive collection of standards compliant, web-based `application programming interface`\nto be able to utilize a wide range of services (i.e., available in a __self-hosted__ or\n__managed hosting__ model). Also, it is available in several __programming languages__\n(e.g., Go, Javascript, Python).\n\nSome of our foundation frameworks (e.g. [Bhojpur GUI](https://github.com/bhojpur/gui) or\n[Bhojpur Application](https://github.com/bhojpur/application)) levevage these\n[APIs](https://github.com/bhojpur/api) for building web-scale `applications` and/or `services`.\n\nBeing a `client-side` library, it compiles without any compilation dependency on the\nservices it tries to access. It is assumed that either HTTP or HTTP/S access should be\nsufficient.\n\n## Bhojpur API - Protocol Buffer Generation\n\nThe application programming interface is defined using protocol buffers. You could generate\nthe client stubs / server skeletons using the following commands.\n\n```bash\n$ make init-proto\n$ make gen-proto\n```\n\nPlease refer to [core](https://github.com/bhojpur/api/tree/main/pkg/core) library for APIs.\n\n## Bhojpur API - WebSocket Access Library\n\nThe `websocket` client/server library is available in __./pkg/websocket__ folder. It supports\nassess using `Javascript` and/or `WebAssembly` for the web.\n\n## Bhojpur API - WebGL Access Library\n\nFirstly, you should install `gopherjs` and verify the system using the following commands.\n\n```bash\n$ go get -u github.com/gopherjs/gopherjs\n$ gopherjs version\n```\n\nThen, try compiling a sample program by issuing the following `gopherjs` command.\n\n```bash\n$ gopherjs build internal/web/main.go\n```\n\nYou need a basic `web server` to run serve the sample files (e.g., .html, .js) using\na standard `web browsers` (e.g., Chrome, Firefox). Therefore, issue the following commands.\n\n```bash\n$ npm install --global http-server\n$ cd internal/web\n$ http-server\n```\n\nNow, open a `web browser` tab and point address to `http://localhost:8080` to see the results.\n\n## Bhojpur API - Client Library\n\nThe `Client` library helps you build [Bhojpur Application](https://github.com/bhojpur/application).\nIt supports all public [Bhojpur APIs](https://docs.bhojpur/reference/api/), while focusing on\nidiomatic Go experience and developer productivity.\n\n### Simple Usage\n\n\u003e Assuming you already have [installed](https://golang.org/doc/install) `Go`\n\nThe Bhojpur API client includes two packages: `client` (for invoking public Bhojpur Application\nruntime APIs), and `service` (to create services that will be invoked by Bhojpur Application\nruntime, this is sometimes referred to as `callback`).\n\n### Creating a Client\n\nimport Bhojpur API `client` package:\n\n```go\nimport \"github.com/bhojpur/api/pkg/client\"\n```\n\n#### Quick start\n\n```go\npackage main\n\nimport (\n    app \"github.com/bhojpur/api/pkg/client\"\n)\n\nfunc main() {\n    client, err := app.NewClient()\n    if err != nil {\n        panic(err)\n    }\n    defer client.Close()\n    // TODO: use the client here, see below for examples \n}\n```\n\nAssuming you have [Bhojpur Application CLI](https://docs.bhojpur.net/getting-started/install-app/)\ninstalled, you can then launch your application locally like this:\n\n```shell\n$ appctl run --app-id example-service \\\n            --app-protocol grpc \\\n            --app-port 50001 \\\n            go run main.go\n```\n\n#### Usage\n\nThe `client` library supports all the building blocks exposed by Bhojpur Application runtime API.\nLet's review these one by one:\n\n##### State\n\nFor simple use-cases, Bhojpur API client provides easy to use `Save`, `Get`, and `Delete` methods:\n\n```go\nctx := context.Background()\ndata := []byte(\"hello\")\nstore := \"my-store\" // defined in the component YAML \n\n// save state with the key key1, default options: strong, last-write\nif err := client.SaveState(ctx, store, \"key1\", data, nil); err != nil {\n    panic(err)\n}\n\n// get state for key key1\nitem, err := client.GetState(ctx, store, \"key1\", nil)\nif err != nil {\n    panic(err)\n}\nfmt.Printf(\"data [key:%s etag:%s]: %s\", item.Key, item.Etag, string(item.Value))\n\n// delete state for key key1\nif err := client.DeleteState(ctx, store, \"key1\", nil); err != nil {\n    panic(err)\n}\n```\n\nFor more granular control, the Bhojpur API client exposes `SetStateItem` type, which can be used\nto gain more control over the state operations and allow for multiple items to be saved at once:\n\n```go\nitem1 := \u0026app.SetStateItem{\n    Key:  \"key1\",\n    Etag: \u0026ETag{\n        Value: \"1\",\n    },\n    Metadata: map[string]string{\n        \"created-on\": time.Now().UTC().String(),\n    },\n    Value: []byte(\"hello\"),\n    Options: \u0026app.StateOptions{\n        Concurrency: app.StateConcurrencyLastWrite,\n        Consistency: app.StateConsistencyStrong,\n    },\n}\n\nitem2 := \u0026app.SetStateItem{\n    Key:  \"key2\",\n    Metadata: map[string]string{\n        \"created-on\": time.Now().UTC().String(),\n    },\n    Value: []byte(\"hello again\"),\n}\n\nitem3 := \u0026app.SetStateItem{\n    Key:  \"key3\",\n    Etag: \u0026app.ETag{\n\tValue: \"1\",\n    },\n    Value: []byte(\"hello again\"),\n}\n\nif err := client.SaveBulkState(ctx, store, item1, item2, item3); err != nil {\n    panic(err)\n}\n```\n\nSimilarly, `GetBulkState` method provides a way to retrieve multiple state items in a single operation:\n\n```go\nkeys := []string{\"key1\", \"key2\", \"key3\"}\nitems, err := client.GetBulkState(ctx, store, keys, nil,100)\n```\n\nAnd, the `ExecuteStateTransaction` method to execute multiple `upsert` or `delete` operations\ntransactionally.\n\n```go\nops := make([]*app.StateOperation, 0)\n\nop1 := \u0026app.StateOperation{\n    Type: app.StateOperationTypeUpsert,\n    Item: \u0026app.SetStateItem{\n        Key:   \"key1\",\n        Value: []byte(data),\n    },\n}\nop2 := \u0026app.StateOperation{\n    Type: app.StateOperationTypeDelete,\n    Item: \u0026app.SetStateItem{\n        Key:   \"key2\",\n    },\n}\nops = append(ops, op1, op2)\nmeta := map[string]string{}\nerr := testClient.ExecuteStateTransaction(ctx, store, meta, ops)\n```\n\n##### PubSub\n\nTo publish data onto a topic, the Bhojpur API client provides a simple method:\n\n```go\ndata := []byte(`{ \"id\": \"a123\", \"value\": \"abcdefg\", \"valid\": true }`)\nif err := client.PublishEvent(ctx, \"component-name\", \"topic-name\", data); err != nil {\n    panic(err)\n}\n```\n\n##### Service Invocation\n\nTo invoke a specific method on another service running with Bhojpur Application runtime sidecar,\nthe Bhojpur API client provides two options. To invoke a service without any data:\n\n```go\nresp, err := client.InvokeMethod(ctx, \"app-id\", \"method-name\", \"post\")\n``` \n\nAnd, to invoke a service with data:\n\n```go\ncontent := \u0026app.DataContent{\n    ContentType: \"application/json\",\n    Data:        []byte(`{ \"id\": \"a123\", \"value\": \"demo\", \"valid\": true }`),\n}\n\nresp, err = client.InvokeMethodWithContent(ctx, \"app-id\", \"method-name\", \"post\", content)\n```\n\n##### Bindings\n\nSimilar to the Service, the Bhojpur API client provides two methods to invoke an operation on a\n[Bhojpur Application defined binding](https://docs.bhojpur.net/developing-applications/building-blocks/bindings/). The Bhojpur Application runtime supports input, output, and bidirectional bindings.\n\nFor simple, output only binding:\n\n```go\nin := \u0026app.InvokeBindingRequest{ Name: \"binding-name\", Operation: \"operation-name\" }\nerr = client.InvokeOutputBinding(ctx, in)\n```\n\nTo invoke method with content and metadata:\n\n```go\nin := \u0026app.InvokeBindingRequest{\n    Name:      \"binding-name\",\n    Operation: \"operation-name\",\n    Data: []byte(\"hello\"),\n    Metadata: map[string]string{\"k1\": \"v1\", \"k2\": \"v2\"},\n}\n\nout, err := client.InvokeBinding(ctx, in)\n```\n\n##### Secrets\n\nThe Bhojpur API client also provides access to the runtime secrets that can be backed by any number of\nsecret stores (e.g. Kubernetes Secrets, HashiCorp Vault, or Azure KeyVault):\n\n```go\nopt := map[string]string{\n    \"version\": \"2\",\n}\n\nsecret, err := client.GetSecret(ctx, \"store-name\", \"secret-name\", opt)\n```\n\n##### Authentication\n\nBy default, the Bhojpur Application runtime relies on the network boundary to limit access to its\nAPI. If however the target Bhojpur Application runtime API is configured with token-based authentication,\nusers can configure the Bhojpur API client with that token in two ways:\n\n###### Environment Variable\n\nIf the `APP_API_TOKEN` environment variable is defined, the Bhojpur Application runtime will automatically\nuse it to augment its Bhojpur Application runtime API invocations to ensure authentication.\n\n###### Explicit Method\n\nIn addition, users can also set the API token explicitly on any Bhojpur API client instance. This approach\nis helpful in cases when the user code needs to create multiple clients for different Bhojpur Application\nruntime API endpoints.\n\n```go\nfunc main() {\n    client, err := app.NewClient()\n    if err != nil {\n        panic(err)\n    }\n    defer client.Close()\n    client.WithAuthToken(\"your-app-API-token-here\")\n}\n```\n\n### Service (callback)\n\nIn addition to the `client` capabilities that allow you to call into the Bhojpur Application runtime API,\nthe Bhojpur API also provides `service` package to help you bootstrap Bhojpur Application runtime callback\nservices in either gRPC or HTTP. Instructions on how to use it are located [here](./pkg/service/README.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbhojpur%2Fapi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbhojpur%2Fapi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbhojpur%2Fapi/lists"}