bitflicker64 opened a new pull request, #490:
URL: https://github.com/apache/hugegraph-doc/pull/490
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`
|
--
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]
