eCorpus plaque de Gédéon et la toison

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 :

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 usage statistics like CPU or memory usage and Database stats like N° of files, date of last modification, etc…

Responses

200

Server statistics

application/json
{
  files: {
    mtime: "string"
    files: number (int)
    size: number (int)
  }
  process: {
    cores: number (int)
    freemem: number (int)
    load: [ number ]
  }
}

post /admin/mailtest

sends a test email to the currently authenticated user’s address.

auth

Authentication, access control querying and edition routes.

get /auth/login

get login data using the current authentication

Also used for login links with a payload query string

Responses

200

The user’s data. If called without authentication, will return a default user.

application/json
{
  uid: "string"  // /^\d+$/
  username: "string"
  email?: "string"
  isAdministrator: boolean
  isDefaultUser?: boolean
}

post /auth/login

log-in to the server

Request Body

The authentication data

application/json
{
  username: "string"
  password: "string"
}

get a login link for this user

Path parameters

:username

human-readable unique name of an user

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 parameter
: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 orderBy:ctimeis used`
:offset

Skip the first n results. Use with limit to paginate results.
: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

required

A 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

required

scene 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

required

Scene 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"
  email?: "string"
  isAdministrator: boolean
  isDefaultUser?: 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)