eCorpus HTTP API
If you're just getting started with the API, you are probably interested in the Scenes section.
For more advanced uses, this API is organized in sections (tags in OpenAPI language), each under a namespace prefix :
-
admin:
Administrative tasks routes
-
auth:
Authentication, access control querying and edition routes.
-
history:
history management utilities for the
/scenes
namespace. Scene names in/history
directly and uniquely maps to scenes in/scenes
. -
scenes:
Where all the actual data is stored API design for the
/scenes/*
makes use of the liberal definition of GET for collections in the webDAV specification to return well-defined JSON documents for those queries, allowing most use cases to bypass cumbersome PROPFIND queries -
tags:
collections (tags) management routes.
-
users:
Users management
Introduction
This HTTP API provides all necessary routes to access and edit scenes stored on an eCorpus instance under the /scenes
path.
Additionally it provides a number of namespaced utilities
for users management (/users
),
authentication and ACL edition (/auth
),
changes history management (/history
)
or gathering scenes under collections (/tags
).
It provides some webDAV utility routes for the /scenes
resources
but is far from Class 1 Compliance:
Only routes that are necessary for proper Voyager support are implemented.
WebDAV-specific methods are defined as an extension with a x-
prefix to prevent breaking openAPI tooling
Other namespaces tends to adhere to a stricter REST philosophy where possible.
admin
Administrative tasks routes
get /admin/stats
get server stats
post /admin/mailtest
sends a test email
auth
Authentication, access control querying and edition routes.
get /auth/login
get login data
post /auth/login
log-in to the server
get /auth/login/{username}/link
get a login link for this user
Path parameters
:username |
human-readable unique name of an user |
post /auth/login/{username}/link
generate and send a login link for this user
Path parameters
:username |
human-readable unique name of an user |
post /auth/logout
delete this request’s credentials
get /auth/access/{scene}
get a scene’s access rights
Path parameters
:scene |
unique name of a scene |
Responses
200
Access map defined for this scene
application/json
[ {
uid: "string" // /^\d+$/
username: "string"
access: "string"
} ]
401
Generic HTTP error response whose content depends on the request’s “Accept” header
application/json
{
code: number (int32)
message: "string"
}
text/plain
"string"
text/html
"string"
patch /auth/access/{scene}
edit a scene’s access rights
Path parameters
:scene |
unique name of a scene |
history
history management utilities for the /scenes
namespace.
Scene names in /history
directly and uniquely maps to scenes in /scenes
.
get /history/{scene}
get a full history of a scene’s modifications
Path parameters
:scene |
unique name of a scene |
post /history/{scene}
edit a scene’s history
Path parameters
:scene |
unique name of a scene |
get /history/{scene}/files
list all files in the scenes in their current state
Path parameters
:scene |
unique name of a scene |
scenes
Where all the actual data is stored
API design for the /scenes/*
makes use of the liberal definition of
GET for collections in the webDAV specification
to return well-defined JSON documents for those queries, allowing most use cases to bypass cumbersome PROPFIND queries
get /scenes
get a list of scenes with optional search parameters. Similar to PROPFIND but will return JSON. Provides advanced search and pagination semantics
Query parameters
:id
|
Scenes IDs to get. If provided, will return only those scenes. Mainly useful for zip download |
:name
|
Scene names to get. If provided, will return only those scenes, ignoring the |
:match
|
Matches a string against a scene’s name, author, authorized users and document meta. See examples for the accepted syntax |
:access
|
Match only scenes for which the current user have the requested access rights |
:limit
|
Limit the number of returned results. A hard maximum of 100 is enforced
Ordering is guaranteed to stay stable when |
:offset
|
Skip the first n results. Use with |
:orderBy
|
Field to use for results sorting |
:orderDirection
|
Switch between ascending and descending order |
Responses
200
A list of scenes matching this query.
By default, returns a JSON object containing basic metadata for all scenes.
Can be used to return a ZIP archive of the matched scenes content.
application/json
{
scenes: [ {
ctime: "string"
mtime: "string"
author_id: "string" // /^\d+$/
author: "string"
id: "string" // /^\d+$/
name?: "string"
thumb?: "string"
access: {
default: "string"
any: "string"
user?: "string"
}
} ]
}
text/plain
"string"
application/zip
Buffer
post /scenes
import an archive of scenes to be extracted into the scenes/
folder
Request Body
requiredA zip file that contains an archived scene hierarchy.
eCorpus uses a simplified internal zip decoder that is guaranteed to handle only data exported from another eCorpus instance. If you wish to create an archive yourself, you have to ensure your archiver stores only uncompressed data using only supported ZIP features
application/zip
Buffer
propfind /scenes
list all readable content in scenes/
. See rfc4918 to learn more about PROPFIND
This is a minimal implementation that just lists contained elements, respecting the Depth header.
While this is not paginated, expect future changes to implement limits on the results’ size.
Responses
200
a PROPFIND multistatus response
application/xml
<D:multistatus xmlns:D="DAV:">
<D:responseDescription>string</D:responseDescription>
<D:response>
<D:href>https://example.com/foo</D:href> <!-- array -- >
<D:propstat>
<D:status>HTTP/1.1 200 OK</D:status>
<D:prop>
<D:getlastmodified>Tue, 28 May 2024 11:59:56 GMT</D:getlastmodified>
<D:creationdate>Tue, 28 May 2024 11:59:56 GMT</D:creationdate>
<D:resourcetype></D:resourcetype>
</D:prop>
</D:propstat>
</D:response> <!-- array -- >
</D:multistatus>
get /scenes/{scene}
get a scene’s metadata.
Path parameters
:scene |
unique name of a scene |
Responses
200
The requested scene’s data
application/json
No schema provided
404
scene not found. It doesn’t exist or isn’t readable with the current authentication
mkcol /scenes/{scene}
creates a new empty scene. This scene will essentially be invisible until populated
Path parameters
:scene |
unique name of a scene |
propfind /scenes/{scene}
fetch the scene’s content
Path parameters
:scene |
unique name of a scene |
delete /scenes/{scene}
Archives a scene
Path parameters
:scene |
unique name of a scene |
Query parameters
:archive
|
Set to false to force-delete scenes (instance administrators only). Otherwise archive it in a way that could be undone by administrators. Defaults to true |
Responses
204
success
401
Unauthorized, either due to improper authentication or insufficient access rights. Archiving a scene requires “admin” rights over it, while force-delete requires instance-level administrative rights.
post /scenes/{scene}
creates a new scene using attached data.
When a GLB model is provided as request body, creates a default scene, initialized with this model positionned at (0,0,0).
Path parameters
:scene |
unique name of a scene |
Request Body
requiredscene initialization data
model/gltf-binary
Buffer
Responses
201
a new scene was created and initialized with a default scene.svx.json
file
409
a scene with this name already exists
patch /scenes/{scene}
Edit scene’s metadata
Path parameters
:scene |
unique name of a scene |
Request Body
requiredScene patch data using a partial object. Check schema for a list of editable fields.
Permissions are additive, to reset a user to default permissions, explicitely set his permission to null
.
Tags are copied: if a tags
field is provided, any tag not included will be removed.
application/json
{
name?: "string"
permissions?: {
}
tags?: [ "string" ]
}
get /scenes/{scene}/{file:.*}
get a file in scene
Path parameters
:scene |
unique name of a scene |
:file |
relative path to a scene’s file. Might contain slashs, though openAPI spec won’t allow them in test queries |
put /scenes/{scene}/{file:.*}
overwrite the file with new content
Path parameters
:scene |
unique name of a scene |
:file |
relative path to a scene’s file. Might contain slashs, though openAPI spec won’t allow them in test queries |
Request Body
The file’s data
*/*
Buffer
copy /scenes/{scene}/{file:.*}
copy a file to another location in the same scene
Path parameters
:scene |
unique name of a scene |
:file |
relative path to a scene’s file. Might contain slashs, though openAPI spec won’t allow them in test queries |
move /scenes/{scene}/{file:.*}
move a file to another location in the same scene
Path parameters
:scene |
unique name of a scene |
:file |
relative path to a scene’s file. Might contain slashs, though openAPI spec won’t allow them in test queries |
delete /scenes/{scene}/{file:.*}
archives a file. It is still accessible through the history API
Path parameters
:scene |
unique name of a scene |
:file |
relative path to a scene’s file. Might contain slashs, though openAPI spec won’t allow them in test queries |
mkcol /scenes/{scene}/{file:.*}
creates a folder in a scene
Path parameters
:scene |
unique name of a scene |
:file |
relative path to a scene’s file. Might contain slashs, though openAPI spec won’t allow them in test queries |
propfind /scenes/{scene}/{file:.*}
get a file’s properties
Path parameters
:scene |
unique name of a scene |
:file |
relative path to a scene’s file. Might contain slashs, though openAPI spec won’t allow them in test queries |
tags
collections (tags) management routes.
get /tags
get a list of tags on this server
get /tags/{tag}
get all scenes associated with this tag
Path parameters
:tag |
name of a tag |
users
Users management
get /users
get a list of registered users
Responses
200
An array of all users registered on this server
application/json
[ {
uid: "string" // /^\d+$/
username: "string"
isAdministrator: boolean
} ]
401
Generic HTTP error response whose content depends on the request’s “Accept” header
application/json
{
code: number (int32)
message: "string"
}
text/plain
"string"
text/html
"string"
post /users
create a new user
Request Body
the user to create
application/json
{
username: "string"
email: "string"
password: "string"
isAdministrator?: boolean
}
Responses
201
user created successfully
400
Generic HTTP error response whose content depends on the request’s “Accept” header
application/json
{
code: number (int32)
message: "string"
}
text/plain
"string"
text/html
"string"
delete /users/{uid}
delete a user
Path parameters
:uid |
unique ID of an user (stays stable through user renames) |
patch /users/{uid}
change a user’s data
Path parameters
:uid |
unique ID of an user (stays stable through user renames) |