Skip to content

REST API

Jump to bottom Edit New page
Alessio Lombardi edited this page Nov 1, 2019 · 15 revisions

Required End-points

All end-points

Set up

Create a Project

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)

Delete a Project

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)

Get Project

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)

Create a Stream

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)

Delete a Stream

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 (download) Stream

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)

Revision

List all Revisions

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

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 two Revisions (diff Revisions)

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

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)

Users and permissions

Get user permissions for a Project

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

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

Get user permission for a Project's Stream

Returns a stream_UserAccess json with the user permissions status.

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

Add an user to the Project

User access level defaults to project default upon creation.

POST /{project_id}/users/{user_id}

Add an user to a Project's Stream

User access level defaults to project default upon creation.

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

Modify single User permissions status for a Project

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 = {}
}

Modify single User permissions for a Project's Stream

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 default User permissions for a Project

Set the default user permissions for a certain project.

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

Set default User permissions for a Project' Stream

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

PUT /{project_id}/{stream_id}/permissions
{
    stream_userAccess = {}
}
Add a custom footer
Add a custom sidebar
Clone this wiki locally