Skip to content

doc(server): sync server-api with master - #490

Open
bitflicker64 wants to merge 1 commit into
apache:masterfrom
bitflicker64:doc-sync/server-server-api
Open

doc(server): sync server-api with master#490
bitflicker64 wants to merge 1 commit into
apache:masterfrom
bitflicker64:doc-sync/server-server-api

Conversation

@bitflicker64

@bitflicker64 bitflicker64 commented Sep 5, 2026

Copy link
Copy Markdown
Contributor

Sync the hugegraph-server/hugegraph-api REST surface with master (36811483a).

Every @Path/@GET/@POST/@PUT/@DELETE in the api module was enumerated and mapped to a doc section, so that every documented endpoint still exists and every existing endpoint is documented. Both content/en and content/cn are updated.

In the table below, .../api/ is short for hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/, and .../config/ for hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/config/.

page what was wrong what changed source (file:line on master)
clients/restful-api/other.md versions reported "api": "0.71.0.0" Bumped to 0.72.0.0 hugegraph-server/hugegraph-api/pom.xml:205, hugegraph-commons/hugegraph-common/src/main/resources/version.properties:20
clients/restful-api/other.md GET / and GET /apis were not documented Added the server profile and the API listing, with their response shapes .../api/profile/ProfileAPI.java:64, .../api/profile/ProfileAPI.java:94
clients/restful-api/other.md The exception trace switch was not documented Added GET/PUT /exception/trace and its relation to exception.allow_trace .../api/filter/ExceptionFilter.java:84, .../config/ServerOptions.java:464
clients/restful-api/other.md The IP allowlist API was not documented Added GET/POST/PUT /whiteiplist with the load/remove actions and the white_ip.status switch .../api/profile/WhiteIpListAPI.java:54, .../config/ServerOptions.java:89
clients/restful-api/other.md The Arthas agent API was not documented Added PUT /arthas and the four arthas.* options it applies .../api/arthas/ArthasAPI.java:38, .../config/ServerOptions.java:432
clients/restful-api/auth.md The login API was missing Added POST /auth/login, DELETE /auth/logout, GET /auth/verify, with the Bearer header requirement and the auth.token_secret/auth.token_expire behaviour .../api/auth/LoginAPI.java:62, hugegraph-server/hugegraph-test/src/main/java/org/apache/hugegraph/api/LoginApiTest.java:82
clients/restful-api/auth.md The project API was missing Added create, add/remove graphs, describe, list, get and delete for /auth/projects .../api/auth/ProjectAPI.java:58
clients/restful-api/auth.md managers/check used type=WRITE and claimed a "true" string body type is required and limited to SPACE/SPACE_MEMBER/ADMIN, the body is {"check": true} .../api/auth/ManagerAPI.java:202, .../api/auth/ManagerAPI.java:312
clients/restful-api/auth.md Manager list body was {"managers": [...]} It is {"admins": ["admin"]}, and type is required .../api/auth/ManagerAPI.java:195
clients/restful-api/auth.md Manager grant body claimed manager_creator/manager_create It is {"user", "type", "graphspace"} .../api/auth/ManagerAPI.java:115
clients/restful-api/auth.md Manager role query body was {"roles": {"boss": ["READ", ...]}} It is {"user", "graphspace", "roles"} over ADMIN/SPACE/SPACE_MEMBER/NONE .../api/auth/ManagerAPI.java:261
clients/restful-api/auth.md managers/default was missing Added the default-role check endpoint .../api/auth/ManagerAPI.java:267
clients/restful-api/auth.md Single-user query showed the {"users": [...]} list wrapper; several 204 sections carried a 1 body Single user returns one object; the bodies were dropped from the 204 sections .../api/auth/UserAPI.java:134, .../api/auth/UserAPI.java:164
clients/restful-api/auth.md Create-user params omitted nickname/avatar/description; list params omitted name; belongs/accesses list params omitted their filters; modify-user claimed user_name can change Added the fields and filters, and noted that the user name is immutable .../api/auth/UserAPI.java:192, .../api/auth/UserAPI.java:105, .../api/auth/BelongAPI.java:119, .../api/auth/AccessAPI.java:137
clients/restful-api/graphs.md Graph create and clone documented status 200 and a two-field body Status is 201 and the body carries name, nickname, backend, description; the optional config fields and their defaults are listed .../api/profile/GraphsAPI.java:452, .../api/profile/GraphsAPI.java:527, .../api/profile/GraphsAPI.java:483
clients/restful-api/graphs.md Read mode note listed OLAP_ONLY as allowed; two mode notes omitted LOADING Read mode is ALL or OLTP_ONLY; LOADING added to the graph mode lists .../api/profile/GraphsAPI.java:716, hugegraph-server/hugegraph-core/src/main/java/org/apache/hugegraph/type/define/GraphMode.java:46
clients/restful-api/graphs.md Graph profile, default graph, nickname update and reload were missing Added GET .../graphs/profile, the {name}/default set/unset and graphs/default read, PUT .../graphs/{name} with action=update, and PUT .../graphs/manage with action=reload .../api/profile/GraphsAPI.java:142, .../api/profile/GraphsAPI.java:252, .../api/profile/GraphsAPI.java:306, .../api/profile/GraphsAPI.java:349, .../api/profile/GraphsAPI.java:428
clients/restful-api/graphs.md Raft group management was not documented Added list_peers, get_leader, transfer_leader, set_leader, add_peer and remove_peer .../api/raft/RaftAPI.java:57
clients/restful-api/graphspace.md The request table marked the namespaces, description and max_role_number as required, and omitted nickname Only name, cpu_limit, memory_limit, storage_limit and max_graph_number are checked; added nickname .../api/space/GraphSpaceAPI.java:588
clients/restful-api/graphspace.md Response bodies omitted nickname, storage_percent, creator, create_time, update_time, and the dp fields of the detail endpoint Added the missing fields to create, get and update hugegraph-server/hugegraph-core/src/main/java/org/apache/hugegraph/space/GraphSpace.java:366, .../api/space/GraphSpaceAPI.java:99
clients/restful-api/graphspace.md Default roles, the graphspace profile list and schema templates were missing Added POST/GET/DELETE /graphspaces/{gs}/role, GET /graphspaces/profile and the five schematemplates endpoints .../api/space/GraphSpaceAPI.java:114, .../api/space/GraphSpaceAPI.java:271, .../api/space/SchemaTemplateAPI.java:57
clients/restful-api/traverser.md A stray ### 3.2 heading split the overview list in the en page Removed it so the list matches the cn page n/a (en-only structure fix)
clients/restful-api/traverser.md Adamic-Adar, resource allocation, edge existence and count were missing Added the four sections and the matching overview entries .../api/traversers/AdamicAdarAPI.java:52, .../api/traversers/ResourceAllocationAPI.java:52, .../api/traversers/EdgeExistenceAPI.java:47, .../api/traversers/CountAPI.java:55
clients/restful-api/task.md Cancel claimed a {"cancelled": true} body; list/get/delete params were incomplete Cancel returns the task object; added ids, page, the limit default, with_result and force, and the full status list .../api/job/TaskAPI.java:203, .../api/job/TaskAPI.java:80, .../api/job/TaskAPI.java:143, .../api/job/TaskAPI.java:165
clients/restful-api/task.md Algorithm and computer jobs were not documented Added both endpoints with the registered names .../api/job/AlgorithmAPI.java:50, hugegraph-server/hugegraph-core/src/main/java/org/apache/hugegraph/job/algorithm/AlgorithmPool.java:46, .../api/job/ComputerAPI.java:50, hugegraph-server/hugegraph-core/src/main/java/org/apache/hugegraph/job/computer/ComputerPool.java:27
clients/restful-api/indexlabel.md The index label update endpoint was missing Added the userdata update with action=append or action=eliminate .../api/schema/IndexLabelAPI.java:97
clients/restful-api/rank.md Neighbor rank top default was 100 and skip_degree was missing; personal rank depth range was [2, 50] top defaults to 10, skip_degree documented, depth range is [2, 5000] .../api/traversers/NeighborRankAPI.java:133, .../api/traversers/NeighborRankAPI.java:131, .../api/traversers/PersonalRankAPI.java:85
clients/restful-api/vertex.md Vertex query params omitted keep_start_p and offset, and claimed page forbids other params Added the params and corrected the constraint to offset only .../api/graph/VertexAPI.java:254, .../api/graph/VertexAPI.java:267
clients/restful-api/cypher.md The mandatory Authorization header was not mentioned Noted that a request without Basic or Bearer credentials returns 401 .../api/cypher/CypherAPI.java:139
config/config-authentication.md auth.token_secret guidance did not mention the random default; the auth.admin_pa comment described it as PD-only Documented the random default and the cases that need an explicit secret, and the real meaning of auth.admin_pa hugegraph-server/hugegraph-core/src/main/java/org/apache/hugegraph/config/AuthOptions.java:71, .../config/ServerOptions.java:481
config/config-https.md Claimed the conf directory already contains hugegraph-server.keystore The keystore is not shipped; bin/start-hugegraph.sh downloads it on the first HTTPS start hugegraph-server/hugegraph-dist/src/assembly/static/bin/start-hugegraph.sh:84, hugegraph-server/hugegraph-dist/pom.xml:226
guides/backup-restore.md Graph mode lists omitted LOADING; "before backup" should be "before restore"; a stray quote in a heading Fixed the mode lists, the wording and the heading hugegraph-server/hugegraph-core/src/main/java/org/apache/hugegraph/type/define/GraphMode.java:46
clients/restful-api/graphs.md The graph creation note told the reader to add "task.scheduler_type": "distributed" for the hstore backend, and the hstore example body carried the key Dropped the key from the example body, and the note now records that it is deprecated and ignored, with the scheduler selected from the backend type hugegraph-server/hugegraph-core/src/main/java/org/apache/hugegraph/StandardHugeGraph.java:229, hugegraph-server/hugegraph-core/src/main/java/org/apache/hugegraph/StandardHugeGraph.java:1652

Versioning call on the hstore note: the sentence stays, saying the key was needed on 1.7.0 and earlier and is now deprecated and ignored, because the site publishes 1.7 and 1.5 builds and the sibling NPE note on the same page already carries its version history the same way. The "(for version 1.7.0 and earlier)" qualifier on the example heading was dropped instead, since with the key gone that example applies to every version.

@bitflicker64
bitflicker64 force-pushed the doc-sync/server-server-api branch 2 times, most recently from 90861e9 to c94c17c Compare September 5, 2026 19:29
Diff every REST resource in hugegraph-api against the docs. Document the
endpoints that were missing: login/logout/verify, auth projects, the
graphspace default-role and schema-template APIs, graph profile, default
graph, nickname update and reload, raft group management, algorithm and
computer jobs, the adamic-adar, resource-allocation, edge-existence and
count traversers, the index label update, the server profile and API
listing, the exception trace switch, the IP allowlist and the Arthas
agent. Fix wrong response shapes and status codes for graph create and
clone, task cancel, manager check/list/grant/role and single-user query,
correct the allowed graph read modes and graph modes, the graphspace
required fields, the neighbor-rank top default and the personal-rank
depth range, add the missing vertex query and task query parameters, and
replace the claim that the HTTPS keystore ships in conf.

Also drop task.scheduler_type from the graph creation example. The key is
no longer a declared config option, setting it is ignored and only logs a
deprecation warning, and the scheduler is picked from the backend type.
The note keeps one sentence of history for readers on 1.7.0 and earlier.
@bitflicker64
bitflicker64 force-pushed the doc-sync/server-server-api branch from c94c17c to abf3a42 Compare September 5, 2026 19:36
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant