docs: update outdated response in vertex api #259

liuxiaocs7 · 2023-06-02T14:11:54Z

SubTask of [Improvement] RESTful API request/response content need update #260

Fix this page: https://hugegraph.apache.org/cn/docs/clients/restful-api/vertex/

Update outdated vertex response
Improve the testing process

Local Tests:

Env: HG-Server depolyed by docker, (ip:port, 192.168.34.164:18080)

schema:

schema.propertyKey("name").asText().ifNotExist().create();
schema.propertyKey("age").asInt().ifNotExist().create();
schema.propertyKey("city").asText().ifNotExist().create();
schema.propertyKey("weight").asDouble().ifNotExist().create();
schema.propertyKey("lang").asText().ifNotExist().create();
schema.propertyKey("price").asDouble().ifNotExist().create();
schema.propertyKey("hobby").asText().valueList().ifNotExist().create();

schema.vertexLabel("person").properties("name", "age", "city", "weight", "hobby").primaryKeys("name").nullableKeys("age", "city", "weight", "hobby").ifNotExist().create();
schema.vertexLabel("software").properties("name", "lang", "price").primaryKeys("name").nullableKeys("lang", "price").ifNotExist().create();

schema.indexLabel("personByAge").onV("person").by("age").range().ifNotExist().create();

1 Create a vertex

curl -i -H "Content-Type: application/json" -d '{"label":"person","properties":{"name":"marko","age":29}}' http://192.168.34.164:18080/graphs/hugegraph/graph/vertices

response:

curl -i -H "Content-Type: application/json" -d '{"label":"person","properties":{"name":"marko","age":29}}' http://192.168.34.164:18080/graphs/hugegraph/graph/vertices
HTTP/1.1 201 Created
Content-Length: 88
Connection: keep-alive
Content-Type: application/json;charset=UTF-8
Keep-Alive: timeout=4
Proxy-Connection: keep-alive

{"id":"1:marko","label":"person","type":"vertex","properties":{"name":"marko","age":29}}

2 Create multiple vertices

curl -i -H "Content-Type: application/json" -d '[{"label":"person","properties":{"name":"marko","age":29}},{"label":"software","properties":{"name":"ripple","lang":"java","price":199}}]' http://192.168.34.164:18080/graphs/hugegraph/graph/vertices/batch

response:

curl -i -H "Content-Type: application/json" -d '[{"label":"person","properties":{"name":"marko","age":29}},{"label":"software","properties":{"name":"ripple","lang":"java","price":199}}]' http://192.168.34.164:18080/graphs/hugegraph/graph/vertices/batch
HTTP/1.1 201 Created
Content-Length: 22
Connection: keep-alive
Content-Type: application/json;charset=UTF-8
Keep-Alive: timeout=4
Proxy-Connection: keep-alive

["1:marko","2:ripple"]

3 Update vertex properties

curl -i -X PUT -H "Content-Type: application/json" -d '{"label":"person","properties":{"age":30,"city":"Beijing"}}' http://192.168.34.164:18080/graphs/hugegraph/graph/vertices/\"1:marko\"?action=append

response:

curl -i -X PUT -H "Content-Type: application/json" -d '{"label":"person","properties":{"age":30,"city":"Beijing"}}' http://192.168.34.164:18080/graphs/hugegraph/graph/vertices/\"1:marko\"?action=append
HTTP/1.1 200 OK
Content-Length: 105
Connection: keep-alive
Content-Type: application/json;charset=UTF-8
Keep-Alive: timeout=4
Proxy-Connection: keep-alive

{"id":"1:marko","label":"person","type":"vertex","properties":{"name":"marko","age":30,"city":"Beijing"}}

4 Batch Update Vertex Properties

add some verticesfor test：

curl -i -H "Content-Type: application/json" -d '[{"label":"person","properties":{"name":"josh","age":32,"city":"Beijing","weight":0.1,"hobby":["reading","football"]}},{"label":"software","properties":{"name":"lop","lang":"java","price":328}}]' http://192.168.34.164:18080/graphs/hugegraph/graph/vertices/batch

response:

curl -i -H "Content-Type: application/json" -d '[{"label":"person","properties":{"name":"josh","age":32,"city":"Beijing","weight":0.1,"hobby":["reading","football"]}},{"label":"software","properties":{"name":"lop","lang":"java","price":328}}]' http://192.168.34.164:18080/graphs/hugegraph/graph/vertices/batch
HTTP/1.1 201 Created
Content-Length: 18
Connection: keep-alive
Content-Type: application/json;charset=UTF-8
Keep-Alive: timeout=4
Proxy-Connection: keep-alive

["1:josn","2:lop"]

Batch Update Vertex Properties results：

curl -i -X PUT -H "Content-Type: application/json" -d '{"vertices":[{"label":"software","type":"vertex","properties":{"name":"lop","lang":"c++","price":299}},{"label":"person","type":"vertex","properties":{"name":"josh","city":"Shanghai","weight":0.2,"hobby":["swiming"]}}],"update_strategies":{"price":"BIGGER","age":"OVERRIDE","city":"OVERRIDE","weight":"SUM","hobby":"UNION"},"create_if_not_exist":true}' http://192.168.34.164:18080/graphs/hugegraph/graph/vertices/batch

response:

curl -i -X PUT -H "Content-Type: application/json" -d '{"vertices":[{"label":"software","type":"vertex","properties":{"name":"lop","lang":"c++","price":299}},{"label":"person","type":"vertex","properties":{"name":"josh","city":"Shanghai","weight":0.2,"hobby":["swiming"]}}],"update_strategies":{"price":"BIGGER","age":"OVERRIDE","city":"OVERRIDE","weight":"SUM","hobby":"UNION"},"create_if_not_exist":true}' http://192.168.34.164:18080/graphs/hugegraph/graph/vertices/batchaph/vertices/batch
HTTP/1.1 200 OK
Content-Length: 278
Connection: keep-alive
Content-Type: application/json;charset=UTF-8
Keep-Alive: timeout=4
Proxy-Connection: keep-alive

{"vertices":[{"id":"2:lop","label":"software","type":"vertex","properties":{"name":"lop","lang":"c++","price":328.0}},{"id":"1:josh","label":"person","type":"vertex","properties":{"name":"josh","age":32,"city":"Shanghai","weight":0.3,"hobby":["reading","football","swiming"]}}]}

5 Delete Vertex Properties

curl -i -X PUT -H "Content-Type: application/json" -d '{"label":"person","properties":{"city":"Beijing"}}' http://192.168.34.164:18080/graphs/hugegraph/graph/vertices/\"1:marko\"?action=eliminate

response:

curl -i -X PUT -H "Content-Type: application/json" -d '{"label":"person","properties":{"city":"Beijing"}}' http://192.168.34.164:18080/graphs/hugegraph/graph/vertices/\"1:marko\"?action=eliminate
HTTP/1.1 200 OK
Content-Length: 88
Connection: keep-alive
Content-Type: application/json;charset=UTF-8
Keep-Alive: timeout=4
Proxy-Connection: keep-alive

{"id":"1:marko","label":"person","type":"vertex","properties":{"name":"marko","age":30}}

6 Get Vertices that Meet the Criteria

curl -i 'http://192.168.34.164:18080/graphs/hugegraph/graph/vertices?label=person&properties=\{%22age%22:30\}&limit=1' \
  --compressed

response:

HTTP/1.1 200 OK
Content-Length: 103
Connection: keep-alive
Content-Encoding: gzip
Content-Type: application/json;charset=UTF-8
Keep-Alive: timeout=4
Proxy-Connection: keep-alive

{"vertices":[{"id":"1:marko","label":"person","type":"vertex","properties":{"name":"marko","age":30}}]}

Paginate through all vertices, retrieve the first page (page without parameter value), limited to 3 records

add some verticesfor test：

curl -i -H "Content-Type: application/json" -d '[{"label":"person","properties":{"name":"peter","age":29,"city":"Shanghai"}},{"label":"person","properties":{"name":"vadas","age":27,"city":"Hongkong"}}]' http://192.168.34.164:18080/graphs/hugegraph/graph/vertices/batch

response:

curl -i -H "Content-Type: application/json" -d '[{"label":"person","properties":{"name":"peter","age":29,"city":"Shanghai"}},{"label":"person","properties":{"name":"vadas","age":27,"city":"Hongkong"}}]' http://192.168.34.164:18080/graphs/hugegraph/graph/vertices/batch
HTTP/1.1 201 Created
Content-Length: 21
Connection: keep-alive
Content-Type: application/json;charset=UTF-8
Keep-Alive: timeout=4
Proxy-Connection: keep-alive

["1:peter","1:vadas"]

Start paging query

curl -i 'http://192.168.34.164:18080/graphs/hugegraph/graph/vertices?page&limit=3' \
  --compressed

response:

curl -i 'http://192.168.34.164:18080/graphs/hugegraph/graph/vertices?page&limit=3' \
  --compressed
HTTP/1.1 200 OK
Content-Length: 227
Connection: keep-alive
Content-Encoding: gzip
Content-Type: application/json;charset=UTF-8
Keep-Alive: timeout=4
Proxy-Connection: keep-alive

{"vertices":[{"id":"2:lop","label":"software","type":"vertex","properties":{"name":"lop","lang":"c++","price":328.0}},{"id":"1:josh","label":"person","type":"vertex","properties":{"name":"josh","age":32,"city":"Shanghai","weight":0.3,"hobby":["reading","football","swiming"]}},{"id":"1:marko","label":"person","type":"vertex","properties":{"name":"marko","age":30}}],"page": "CIYxOnBldGVyAAAAAAAAAAM="}

search next page results：

curl -i 'http://192.168.34.164:18080/graphs/hugegraph/graph/vertices?page=CIYxOnBldGVyAAAAAAAAAAM=&limit=3' \
  --compressed

response:

curl -i 'http://192.168.34.164:18080/graphs/hugegraph/graph/vertices?page=CIYxOnBldGVyAAAAAAAAAAM=&limit=3' \
  --compressed
HTTP/1.1 200 OK
Content-Length: 186
Connection: keep-alive
Content-Encoding: gzip
Content-Type: application/json;charset=UTF-8
Keep-Alive: timeout=4
Proxy-Connection: keep-alive

{"vertices":[{"id":"1:peter","label":"person","type":"vertex","properties":{"name":"peter","age":29,"city":"Shanghai"}},{"id":"1:vadas","label":"person","type":"vertex","properties":{"name":"vadas","age":27,"city":"Hongkong"}},{"id":"2:ripple","label":"software","type":"vertex","properties":{"name":"ripple","lang":"java","price":199.0}}],"page": null}

7 Retrieve Vertex by ID

curl -i 'http://192.168.34.164:18080/graphs/hugegraph/graph/vertices/%221:marko%22'

response:

curl -i 'http://192.168.34.164:18080/graphs/hugegraph/graph/vertices/%221:marko%22'
HTTP/1.1 200 OK
Content-Length: 88
Connection: keep-alive
Content-Type: application/json;charset=UTF-8
Keep-Alive: timeout=4
Proxy-Connection: keep-alive

{"id":"1:marko","label":"person","type":"vertex","properties":{"name":"marko","age":30}}

Delete the vertex based on ID only.

curl -i -X DELETE 'http://192.168.34.164:18080/graphs/hugegraph/graph/vertices/%221:marko%22'

response:

curl -i -X DELETE 'http://192.168.34.164:18080/graphs/hugegraph/graph/vertices/%221:marko%22'
HTTP/1.1 204 No Content
Connection: keep-alive
Keep-Alive: timeout=4
Proxy-Connection: keep-alive

Delete Vertex by Label+ID

curl -i -X DELETE 'http://192.168.34.164:18080/graphs/hugegraph/graph/vertices/%221:marko%22?label=person'

response:

curl -i -X DELETE 'http://192.168.34.164:18080/graphs/hugegraph/graph/vertices/%221:marko%22?label=person'
HTTP/1.1 204 No Content
Connection: keep-alive
Keep-Alive: timeout=4
Proxy-Connection: keep-alive

imbajin

And it's nice to use GPT/New Bing to enhance the english/chinese typo problem.

Just past the url/phrase into it, ask for the improvement, then it will give us a string of suggestions

content/cn/docs/clients/restful-api/vertex.md

imbajin

This PR is a nice example for others to refer/improve the outdated doc

imbajin

Nice improvement, could also add the (basic) pic/steps for others to refer~

* optimize by new-bing 37a1cb5

liuxiaocs7 added 5 commits June 2, 2023 22:10

docs: update vertex response

4b5e90b

fix en

cde91d4

add schema in en

a29d328

fix json format

11cf3de

update en

998ff47

liuxiaocs7 changed the title ~~docs: update vertex response~~ docs: update outdated vertex response Jun 2, 2023

liuxiaocs7 changed the title ~~docs: update outdated vertex response~~ docs: update outdated response in vertex api Jun 2, 2023

imbajin reviewed Jun 3, 2023

View reviewed changes

content/cn/docs/clients/restful-api/vertex.md Outdated Show resolved Hide resolved

content/cn/docs/clients/restful-api/vertex.md Outdated Show resolved Hide resolved

fix typos

1cc2bbd

imbajin previously approved these changes Jun 3, 2023

View reviewed changes

optimize by new-bing

fa307c7

liuxiaocs7 dismissed imbajin’s stale review via fa307c7 June 3, 2023 17:01

fix

72a6584

liuxiaocs7 mentioned this pull request Jun 3, 2023

[Improvement] RESTful API request/response content need update #260

Open

14 tasks

imbajin approved these changes Jun 4, 2023

View reviewed changes

imbajin merged commit 37a1cb5 into apache:master Jun 4, 2023
1 check passed

github-actions bot pushed a commit that referenced this pull request Jun 4, 2023

docs: update outdated response in vertex api (#259)

3833ea2

* optimize by new-bing 37a1cb5

liuxiaocs7 mentioned this pull request Jun 28, 2023

doc: update outdated doc for edge api #276

Merged

liuxiaocs7 mentioned this pull request Sep 21, 2023

调用创建多个顶点api报错404（/graphs/hugegraph/hugegraph_test/vertices/batch） apache/incubator-hugegraph#2316

Closed

1 task

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: update outdated response in vertex api #259

docs: update outdated response in vertex api #259

liuxiaocs7 commented Jun 2, 2023 •

edited

imbajin left a comment

imbajin left a comment •

edited

imbajin left a comment

docs: update outdated response in vertex api #259

docs: update outdated response in vertex api #259

Conversation

liuxiaocs7 commented Jun 2, 2023 • edited

1 Create a vertex

2 Create multiple vertices

3 Update vertex properties

4 Batch Update Vertex Properties

5 Delete Vertex Properties

6 Get Vertices that Meet the Criteria

Paginate through all vertices, retrieve the first page (page without parameter value), limited to 3 records

7 Retrieve Vertex by ID

Delete the vertex based on ID only.

Delete Vertex by Label+ID

imbajin left a comment

Choose a reason for hiding this comment

imbajin left a comment • edited

Choose a reason for hiding this comment

imbajin left a comment

Choose a reason for hiding this comment

liuxiaocs7 commented Jun 2, 2023 •

edited

imbajin left a comment •

edited