• Set up
  • Create a Project
  • Delete a Project
  • Get Project
  • Create a Stream
  • Delete a Stream
  • Get (download) Stream
• Revision
  • List all Revisions
  • Get a single Revision
  • Get Delta between two Revisions (diff Revisions)
  • Upload a new Revision
• Users and permissions
  • Get user permissions for a Project
  • Get user permission for a Project's Stream
  • Add an user to the Project
  • Add an user to a Project's Stream
  • Modify single User permissions status for a Project
  • Modify single User permissions for a Project's Stream
  • Set default User permissions for a Project
  • Set default User permissions for a Project' Stream

Creates a new Project under a certain user account.

Request:

POST /projects/{project_name}

Where {project_name} is a string.

Responses:

• If successful:

  201 (Created)
  {
      project_id: <uuid> (auto-generated)
  }
  

• If project naming conflict: 409 (Conflict)
• If user does not have rights to create project: 401 (Not authorized)

Request:

DELETE /projects/{project_id}

where project_id is a <uuid>.

Responses:

• If successful: 200 (Ok)
• If the delete action has been queued: 202 (Accepted)
• If project_id is not found or invalid: 404 (Not found)
• If user does not have rights to delete project: 401 (Not authorized)

Request:

GET /projects/{project_id}

where project_id is a <uuid>.

Responses:

• If found:

  200 (Ok)
  {
      project_name: <string>
      streams: [stream_id_01, stream_id_02, ...] (list of stream <uuid>s)
  }
  

• If project_id not found or invalid: 404 (Not Found)

POST /{project_id}/streams
{
    stream_id: <uuid> (optional)
    stream_description: <string> (optional)
}

Responses:

• If successful:

  200 (Ok)
  {
      stream_id: <uuid> (either as supplied or autogenerated)
  }
  

• If project naming conflict: 409 (Conflict)
• If user does not have rights to create streams in this project: 401 (Not authorized)

Request:

DELETE /{project_id}/streams/{stream_id}

where project_id and stream_id are <uuid>s.

Responses:

• If successful: 200 (Ok)
• If the delete action has been queued: 202 (Accepted)
• If project_id is not found or invalid: 404 (Not found)
• If user does not have rights to delete project: 401 (Not authorized)

GET /{project_id}/streams/{stream_id}

where project_id and stream_id are <uuid>s.

Responses:

• If successful:

  200 (Ok)
  {
      stream_id: <uuid>
      description: <string> 
      payload: [<object>]
  }
  

• If stream_id not found or invalid: 404 (Not Found)

Returns a list of revision IDs existing under a certain stream, given a stream ID.

GET /{project_id}/streams/{stream_id}/revisions

where project_id and stream_id are <uuid>s.

Responses:

• If successful:

  200 (Ok)
  {
      stream_id: <uuid>
      description: <string> 
      revisions: [revision_id_01, revision_id_02, ...] (list of all revisions)
  }
  

• If {project_id} or {stream_id} not found or invalid: 404 (Not Found)

Get a single revision contents (given a revision ID)

GET /{project_id}/streams/{stream_id}/revisions/{revision_id}

where project_id, stream_id and revision_id are <uuid>s.

Responses:

• If successful:

  200 (Ok)
  {
      revision_datetime: <DateTime>
      author: {username}
      other ?
      payload: [objects] (revision's content)
  }
  

• If {project_id} or {stream_id} not found or invalid: 404 (Not Found)

Get delta between revisions, meaning all objects that changed revision A and revision B (given rev A and B ids)

GET /{project_id}/{stream_id}/revisions/{revision_id_01}/diff/{revision_id_02}

where project_id, stream_id, revision_id_01 and revision_id_02 are <uuid>s.

Responses:

• If successful:

  200 (Ok)
  {
      revision_datetime: <DateTime>
      author: {username}
      other ?
      delta:  {
        "created": [ 
                       [ uid_1, sid_1, mesh_1, material/colour_1, metadata_1, authoring_tool_1, ... ], 
                       [ uid_2, sid_2, mesh_2, material/colour_2, metadata_2, authoring_tool_2, ... ], 
                       ... 
                    ],
         "deleted": [ uid_4, uid_5, uid_6, ... ],
         "updated": [ 
                       [ uid_7, sid_7, mesh_7, material/colour_7, metadata_7, authoring_tool_7, ... ], 
                       [ uid_8, sid_8, mesh_8, material/colour_8, metadata_8, authoring_tool_8, ... ], 
                       ... 
                     ]
         "revision_A": from_id,
         "revision_B": to_id,
         "timestamp": <time_t>,
         "signature": <base64 AES string>,
         "sender": <string> // E.g. BHoM, 3D Repo, Speckle, etc.
      }
  }
  

• If project_id and stream_id are not found: 404 (Not Found)
• If revision_id_01, revision_id_02 are the same or invalid: 400 (Bad Request)

Upload a new revision by bumping a delta of a stream (provide a stream ID and a delta)

POST /{project_id}/{stream_id}/revisions/
{

    delta = 
    {
      "created": [ 
                     [ uid_1, sid_1, mesh_1, material/colour_1, metadata_1, authoring_tool_1, ... ], 
                     [ uid_2, sid_2, mesh_2, material/colour_2, metadata_2, authoring_tool_2, ... ], 
                     ... 
                  ],
       "deleted": [ uid_4, uid_5, uid_6, ... ],
       "updated": [ 
                     [ uid_7, sid_7, mesh_7, material/colour_7, metadata_7, authoring_tool_7, ... ], 
                     [ uid_8, sid_8, mesh_8, material/colour_8, metadata_8, authoring_tool_8, ... ], 
                     ... 
                   ]
       "revision_A": from_id,
       "revision_B": to_id,
       "timestamp": <time_t>,
       "signature": <base64 AES string>,
       "sender": <string> // E.g. BHoM, 3D Repo, Speckle, etc.
    }
}

where project_id, stream_id, are <uuid>s.

Responses:

• If successful:

  200 (Ok)
  {
      revision_id: <uuid>
  }
  

• If delta object misses info: 400 (Bad Request)

Returns a project_userAccess json with the user permissions/admin status.

GET /{project_id}/users/{user_id}/permissions

Returns a stream_UserAccess json with the user permissions status.

GET /{project_id}/{stream_id}/{user_id}/permissions

User access level defaults to project default upon creation.

POST /{project_id}/users/{user_id}

User access level defaults to project default upon creation.

POST /{project_id}/{stream_id}/users/{user_id}

This can be used to:

• modify one or more permissions for an user of a Project: add/remove/modify one or more permission
• make an user Project Admin / remove Admin status for an user

User access level set with this overrides the Project's default permissions for the user specified.

PUT /{project_id}/users/{user_id}/permissions
{
    project_userAccess = {}
}

This can be used to modify one or more permissions for an user of a Project's Stream: add/remove/modify one or more permission.

User access level defers to parent Project's default permissions where not specified. User access level set with this overrides the Project's Stream default permissions for the user specified.

PUT /{project_id}/{stream_id}/users/{user_id}/permissions
{
    stream_userAccess = {}
}

Set the default user permissions for a certain project.

PUT /{project_id}/permissions
{
    project_userAccess = {}
}

Set the default user permissions for a certain Project's Stream.

PUT /{project_id}/{stream_id}/permissions
{
    stream_userAccess = {}
}