imbajin commented on code in PR #552: URL: https://github.com/apache/hugegraph-doc/pull/552#discussion_r4413150710
########## content/en/docs/quickstart/toolchain/http-api.md: ########## @@ -0,0 +1,247 @@ +--- +title: "Server and Hubble HTTP API Examples" +linkTitle: "HTTP API Examples" +description: "Select GraphSpace Gremlin bindings, submit asynchronous jobs, log in to Hubble, and create schema through HTTP." +weight: 3 +--- + +These examples target Server and Toolchain `master` (1.8). Server and Hubble have separate HTTP listeners and request contracts. +Replace the addresses, credentials, graph names and returned IDs with those from your deployment. +For Helm Service discovery, see the [Helm guide](/docs/quickstart/hugegraph/hugegraph-helm/). + +## Server paths and graph selection + +`GET /apis` is the resource index. Listed resource paths belong under the Server origin: +use `/versions`, `/graphspaces` and `/gremlin`, without prepending `/apis`. +Earlier indexes return paths without a leading slash; interpret those relative to the Server root, not the index directory. +When a gateway adds a public prefix, retain that prefix. + +`GET /graphspaces` requires PD mode. In standalone mode, skip that step and use `GET /graphs` to list configured graphs. + +```bash +curl 'http://localhost:8080/versions' +curl 'http://localhost:8080/graphspaces' +curl 'http://localhost:8080/graphspaces/DEFAULT/graphs' +``` + +Graph creation uses `POST /graphspaces/{space}/graphs/{graph}` and the backend's graph configuration. +`POST /graphs` is not the graph-creation endpoint. The legacy `/graphs` listing does not mean GraphSpace APIs are unavailable. +For the SeaTunnel demo, create `graph_a` before running the supplied sink job, as required by the +[SeaTunnel guide](https://github.com/apache/hugegraph/blob/master/helm/hugegraph/docs/seatunnel.md). + +The synchronous Gremlin endpoint needs aliases for the graph selected by the caller. +For GraphSpace `DEFAULT` and graph `hugegraph`, use these exact binding names: + +```bash +curl -X POST 'http://localhost:8080/gremlin' \ + -H 'Content-Type: application/json' \ + -d '{"gremlin":"g.V().count()","aliases":{"graph":"DEFAULT-hugegraph","g":"__g_DEFAULT-hugegraph"}}' +``` + +Bindings are case-sensitive: `<space>-<graph>` selects the graph and `__g_<space>-<graph>` selects its traversal source. +There is no implicit global `g` on a multi-graph Server. `bindings` supplies query variables; +it does not register graphs, and an alias target cannot be the expression `graph.traversal()`. +For a legacy standalone graph without a GraphSpace, the bindings are `<graph>` and `__g_<graph>`. +For an authenticated Server, add its configured HTTP credentials, for example `-u "$HG_USER:$HG_PASSWORD"`. + +## Long queries use asynchronous jobs + +The default synchronous Gremlin evaluation timeout is 30000 milliseconds, configured by `evaluationTimeout` in `gremlin-server.yaml`. +A whole-graph count can use a different execution path from a filtered label count. Do not infer label-scan latency from `g.V().count()`. +Submit queries that may exceed the synchronous limit as Server tasks: + +```bash +curl -X POST 'http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/jobs/gremlin' \ + -H 'Content-Type: application/json' \ + -d '{"gremlin":"g.V().hasLabel(\"person\").count()"}' + +# Replace <task_id> with the ID from the submission response. +curl 'http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/tasks/<task_id>' +``` + +The job binds `graph` and `g` for the graph in its URL. Poll until `task_status` is terminal and inspect `task_result`. +A task still marked `running` does not yet provide a completed count. Add the same authentication used by other Server requests. +A Hubble transport timeout is separate from the Server evaluation timeout; increasing only one does not remove the other. + +## Hubble login and query bodies + +In authenticated mode, log in with **snake_case** field names and retain the session cookie: + +```bash +curl -c hubble.cookies -X POST 'http://localhost:8088/api/v1.3/auth/login' \ + -H 'Content-Type: application/json' \ + -d '{"user_name":"<username>","user_password":"<password>"}' +``` + +Camel-case `userName` and `userPassword` do not populate this login model. Repeated failed attempts can return HTTP 429; +correct the fields and credentials before retrying. Anonymous mode does not use the login endpoint. + +The integration Gremlin endpoint currently requires `username` and `password` in the body as well as the authenticated session: + +```bash +curl -b hubble.cookies -X POST \ + 'http://localhost:8088/api/v1.3/graphspaces/DEFAULT/graphs/hugegraph/gremlin' \ + -H 'Content-Type: application/json' \ + -d '{"query":"g.V().count()","username":"<username>","password":"<password>"}' +``` + +Use HTTPS outside a trusted local network: JSON does not encrypt these credentials. +This integration body differs from Server's `gremlin` field and from Hubble's workspace `gremlin-query` contract. +The session establishes the caller identity; body credentials do not replace the login cookie. + +## Hubble schema defaults + +Create a vertex label through Hubble using its schema model: + +```bash +curl -b hubble.cookies -X POST \ + 'http://localhost:8088/api/v1.3/graphspaces/DEFAULT/graphs/hugegraph/schema/vertexlabels' \ + -H 'Content-Type: application/json' \ + -d '{"name":"http_demo_person","id_strategy":"AUTOMATIC","properties":[]}' +``` + +Missing or null `style` uses the standard visual style, displaying `~id`; +missing or null `open_label_index` defaults to `true`, and an explicit `false` is preserved. Review Comment: **Clarify the build prerequisite for the schema-default example** The PR description correctly identifies the companion [🔗 Toolchain #859](https://github.com/apache/hugegraph-toolchain/pull/859), but the published page itself says it targets `master` (1.8) and presents a vertex-label request without `style` or `open_label_index` as working with safe defaults. The Chinese example and explanation at `content/cn/docs/quickstart/toolchain/http-api.md:92–97` have the same prerequisite gap. On the independently pinned [current ASF Toolchain source](https://github.com/apache/hugegraph-toolchain/blob/e8476e765a5ec0649e5edd7b2f710d554a179f40/hugegraph-hubble/hubble-be/src/main/java/org/apache/hugegraph/entity/schema/VertexLabelEntity.java#L55-L59), both fields remain nullable. The POST validation reaches [`checkDisplayFields()`](https://github.com/apache/hugegraph-toolchain/blob/e8476e765a5ec0649e5edd7b2f710d554a179f40/hugegraph-hubble/hubble-be/src/main/java/org/apache/hugegraph/controller/schema/VertexLabelController.java#L266-L268), which dereferences the missing style; if style is supplied but `open_label_index` is omitted, [`convert()`](https://github.com/apache/hugegraph-toolchain/blob/e8476e765a5ec0649e5edd7b2f710d554a179f40/hugegraph-hubble/hubble-be/src/main/java/org/apache/hugegraph/service/schema/VertexLabelService.java#L368-L382) passes the nullable Boolean to `enableLabelIndex`. Please state on both pages that the new defaults require a build containing [🔗 Toolchain #859](https://github.com/apache/hugegraph-toolchain/pull/859), or make the main copy/paste example work on the current baseline by including `"open_label_index":true,"style":{"display_fields":["~id"]}`. This is a documentation/version-prerequisite issue, not a newly introduced runtime vulnerability. Evidence is source-level; no live deployment request was executed. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
