File API release notes

Supported API versions

The following File API versions are currently supported:

• 2.0.0
• 1.0.0

Changes

2.10.0

This change adds a preview api header value of enable-no-leading-or-trailing-whitespaces-check, to turn on a check that all paths across File API are now verified to ensure each path segment has no leading or trailing whitespaces. This reduces ambiguity in paths that could be caused by the old behavior where white spaces were allowed. E.g. path/with/a/ leading/ space is no longer valid with an appropriate substitution being path/with/a/leading/space. If an invalid path is passed into one of the endpoints it will fail with:

Example error response

{
    "status": 400,
    "title": "Invalid Path.",
    "detail": "Object names or path segments starting with or ending with a space (' ') are not permitted.",
    "type": "https://seequent.com/error-codes/file-api/files/invalid-path"
}

2.9.0

This update ensures that file names (defined as the last segment in the path) comply with the maximum length restriction of 256 characters. This is to prevent potential issues with other file systems. The validation applies across all endpoints that involve file uploads and updates by path.

Example error response

{
    "status": 400,
    "title": "Invalid Path.",
    "detail": "File name is too long, must be less than 256 characters",
    "type": "https://seequent.com/error-codes/file-api/files/invalid-path"
}

2.7.1

The "Update file by ID" now returns only a DownloadFileResponse body with a 200 OK response. Previously it was incorrectly documented that it may also return a UploadFileResponse body, which is actually only returned with a 303 See Other response.

2.6.0

All created_at datetimes now include an explicit timezone

While all times returned from the API are in UTC, they were being returned as naive datetimes. This change makes them timezone aware, appending a Z to the timestamp.

{
-     "created_at": "2024-03-27T04:27:04"
+     "created_at": "2024-03-27T04:27:04Z"
}

File paths/names are now case-insensitive

Previously, two files with the same path and name could exist at the same time, as long as they were using different cases. This is no longer possible. For example, if you have a file at the path a/b/file.txt and you then upload a file at /a/b/FILE.txt, it will be treated as a new version of the existing file.

2.5.0

All version_id fields are now expected to be strings, and not integers

This change is to allow API consumers to avoid issues that come with handling large numbers. The version ID still represents a positive 64bit signed integer, but will always be handled as a string.

{
    "id": "05f93511-35fd-4e80-96a3-47d1cf102aee",
    "version_id": "1223372036854775807"
}

2.4.3, 1.3.1

• Route definitions that previously used a * suffix parameter now explicitly use a {file_path} parameter.

2.4.2

• Version 2 "list files" API now includes total parameter, indicating the total number of records that match query filters provided (outside of limit and offset).

2.4.0

Rename author to created_by in all responses

Each file upload results in a new file version, so there is only ever a created_by field on each version. Versions cannot be modified, hence no modified_by. The contents remain the same:

{
    "id": "05f93511-35fd-4e80-96a3-47d1cf102aee",
    "name": "Joe Bloggs",
    "email": "Joe.Bloggs@bentley.com"
}

2.0.0

New features

• Version 2 of the API is served at file/v2/...
• Files are now stored in workspaces. A workspace must be created before any files can be uploaded.

Uploading a file

PUT file/v2/orgs/{org_id}/workspaces/{workspace_id}/files/path/{file_path}

File uploads now return a file_id, version_id, and an upload link.

Uploading a new file version

Files can now be uploaded via a path or file ID.

PUT /file/v2/orgs/{org_id}/workspaces/{workspace_id}/files/path/{file_path}

PUT /file/v2/orgs/{org_id}/workspaces/{workspace_id}/files/{file_id}

Download a file

Files can now be downloaded via a path or file ID.

GET .../file/v2/orgs/{org_id}/workspaces/{workspace_id}/files/path/{file_path}

GET .../file/v2/orgs/{org_id}/workspaces/{workspace_id}/files/{file_id}

Delete a file

Files can now be soft-deleted via a path or file ID.

DELETE .../file/v2/orgs/{org_id}/workspaces/{workspace_id}/files/path/{file_path}

DELETE .../file/v2/orgs/{org_id}/workspaces/{workspace_id}/files/{file_id}

List files

GET .../file/v2/orgs/{org_id}/workspaces/{workspace_id}/files