Univer Server API Protocol

rule

  1. the parameter with * mean it is required.
  2. the response with . mean json object properties.
  3. GET and DELETE method parameters only can set in pathinfo or query.
  4. POST, PUT and PATCH method need content-type: application/json request header in most api.

Create Unit

POST /universer-api/snapshot/{type}/unit/-/create

parameters:

nametypedescription
typeenum(int) *1(doc), 2(sheet)
pathinfo and body
namestring *Unit name
creatorstring *The creator user id

response:

nametypedescription
error.codeenum(int)1(success)
error.messagestringThe information of fail situation
unitIDstringUnit id

example:

curl http://localhost:8000/universer-api/snapshot/2/unit/-/create \
  -X POST \
  -H 'Content-Type: application/json' \
  --data-raw '{"type":2,"name":"New Sheet By Univer","creator":"userID"}'
 
# response
{"error":{"code":1, "message":""}, "unitID":"ETVf-B4lQqOSE_p09mcp9Q"}

List Unit

GET /universer-api/snapshot/{type}/units

parameters:

nametypedescription
typeenum(int) *1(doc), 2(sheet)
pathinfo param
nextCursorstringThe cursor for next page

response:

nametypedescription
error.codeenum(int)1(success)
error.messagestringThe information of fail situation
unitsarray[object]
.unitIDstringUnit id
.namestringUnit name
.typeenum(int)1(doc), 2(sheet)
nextCursorstringThe cursor for next page, when empty it is last page

example:

curl -X GET 'http://localhost:8000/universer-api/snapshot/1/units?nextCursor=100'
 
# response
{"error":{"code":1, "message":""},"units":[{"unitID":"1","name":"a","type":1}],"nextCursor":"200"}

Delete Unit

DELETE /universer-api/snapshot/-/units

parameters:

nametypedescription
unitIdsarray[string] *Unit ids

response:

nametypedescription
error.codeenum(int)1(success)
error.messagestringThe information of fail situation

example:

curl -X DELETE 'http://localhost:8000/universer-api/snapshot/-/units?unitIds=1&unitIds=2'
 
# response
{"error":{"code":1, "message":""}}

Upload file

POST /universer-api/stream/file/upload

  1. The request body is a HTLM form, so need request header like it: content-type: multipart/form-data;boundary=---------------------------163876677831359887162093904846.
  2. Note that size parameter must be equal the real file size, if not equal it will product a api error.

parameters:

nametypedescription
sizeint *File size (byte), query parameter
fileForm.file *Use HTLM form to upload file

response:

nametypedescription
FileIdstringThe file id for next api using, like import ane export

example:

curl 'http://localhost:8000/universer-api/stream/file/upload?size=19261' \
  -X POST \
  -H 'Content-Type: multipart/form-data; boundary=---------------------------163876677831359887162093904846' \
  --data-binary $'-----------------------------163876677831359887162093904846\r\nContent-Disposition: form-data; name="file"; filename="test.xlsx"\r\nContent-Type: application/wps-office.xlsx\r\n\r\n-----------------------------163876677831359887162093904846--\r\n'
 
# response
{"FileId":"xxxx"}

Import

POST /universer-api/exchange/{type}/import

parameters:

nametypedescription
typeenum(int) *1(doc), 2(sheet)
outputTypeenum(int) *1(unit), 2(json)
fileIDstring *The upload file id

response:

nametypedescription
error.codeenum(int)1(success)
error.messagestringThe information of fail situation
taskIDstringThe exchange task id, because of import is a async task, so need to polling to get result

example:

curl 'http://localhost:8000/universer-api/exchange/2/import' \
  -X POST \
  -H 'Content-Type: application/json' \
  --data-raw \
  '{"fileID":"123","outputType":1}'
 
# response
{"error":{"code":1,"message":""},"taskID":"456"}

Export

POST /universer-api/exchange/{type}/export

parameters:

nametypedescription
typeenum(int) *1(doc), 2(sheet)
unitIDstring *The Unit id

response:

nametypedescription
error.codeenum(int)1(success)
error.messagestringThe information of fail situation
taskIDstringThe exchange task id, because of export is a async task, so need to polling to get result

example:

curl 'http://localhost:8000/universer-api/exchange/2/export' \
  -X POST \
  -H 'Content-Type: application/json' \
  --data-raw \
  '{"unitID":"xxxx","type":2}'
 
# response
{"error":{"code":1,"message":""},"taskID":"456"}

Get exchange task result

GET /universer-api/exchange/task/{taskID}

parameters:

nametypedescription
taskIDstring *The import or export task id

response:

nametypedescription
error.codeenum(int)1(success)
error.messagestringThe information of fail situation
statusenum(string)pending, done, failed
export.fileIDstringThe export exchange result file id, it use for next api to get file content
import.unitIDstringThe import exchange for unit, it use to open online file
import.jsonIDstringThe import exchange json result file id, it use for next api to get file content

example:

curl -X GET 'http://localhost:8000/universer-api/exchange/task/123'
 
# reponse(import)
{"error":{"code":1,"message":""},"taskID":"123","status":"done","import":{"jsonID":"456"}}
 
# response(export)
{"error":{"code":1,"message":""},"taskID":"123","status":"done","export":{"fileID":"456"}}

Get file

GET /universer-api/file/{fileID}/sign-url

  1. The api return a file download url, it can used to get file content.

parameters:

nametypedescription
fileIDstring *The exchange result file id which need to download

response:

nametypedescription
error.codeenum(int)1(success)
error.messagestringThe information of fail situation
urlstringThe download url

example:

curl -X GET 'http://localhost:8000/universer-api/file/1234/sign-url'
 
# response
{"error":{"code":1,"message":""},"url":"https://192.168.50.74:19000/univer/file/123/univer-2060360000.xlsx"}