Create a way to have a top-level project

[cosmo0]

As the API stands, a project seem to correspond to different parts of a construction project: project A is the west wing of the building, project B is the east wing. Or a railway would be split into stations, rail sections, etc.

There is a problem when we have users intervening for multiple clients. For instance, a superviser could work for both a school for client A and a railway for client B. Both clients could have split their work into several hundreds (or even thousands) "projects". How would that work out for the user? Either they see all projects of all clients they work with, and in that case, there is not enough information in the returned data to filter (just a name and ID ???). Or there could have some parameter to filter the projects for a client.

[GeorgDangl]

@falknes would you mind explaining this a bit, since you have the same requirement?

[cosmo0]

I don't know about them, but here is our problem, in a more detailed way.

We have a cloud-based, SAAS solution. So all users connect to the same server, all clients share the same database.

We define clients/customers/companies in the back office, they have contracts with options etc. Let's say A Building Company (ABC) has several thousand projects, some handled by our solution, some by our competitors.

So the company has multiple projects: let's say ABC builds a school, an office, and a railway, using our solution. These are what we call "workspaces".

Inside these workspaces there are what we call "documents", basically, files with metadata. For instance, a school can have multiple buildings ; each building will have their own document, but they can also be split in sub-documents for architecture, structure, electricity, etc. Each document can have a separate review where notes are created ("there's a problem here") and comments are made on these notes.

Our assumption is that what we call "documents" are what BCF calls "projects". It's the only mapping that makes sense, at least with our client's use cases. What we call "notes" are "BCF topics". There is no BCF concept for our workspaces.

As a side note, lots of workspaces have several tens of thousands of documents, and very large projects are split into multiple workspaces.

---

Now, most users (physical person) will have a single workspace. The problem arises with "power users", experts in their field, that work on multiple project for multiple clients: they handle thousands of documents across dozens of workspaces, and since they are experts, they are likely to do a project review, and thus, use the BCF API.

So, these users must have a way to distinguish between "BCF projects": calling /bcf/3.0/projects just cannot send them thousands of entries mixing a school, an office and a railway, both for client X and client Y, especially if the only data they see is a name. Not to mention that it's a nightmare to handle access rights in this scenario.

---

The way I see it, there are two possibilities.

One: consider that most cloud-based/SAAS solutions will have the same problem, and break existing routes. For example, you could prefix all routes with /clients/{client_id}/ or something: so the list of projects would become /bcf/3.0/clients/{client_id}/projects/. This solution is flexible (a client could be whatever we want) and "restful", but API clients would need to be rewritten entirely.

Two: keep the existing routes, but:

• add a client query string parameter to the /projects route, and allow API endpoints to make the parameter mandatory (maybe described in a metadata endpoint somewhere).
• add a /clients route to list the possible clients (id, name, code)

This would require the least amount of modifications for an API client (a new route and a new parameter), but it's also less "clean".
Catenda already uses a bimsync_project_id (https://hub.catenda.com/developers/reference/bcf/v3_0#get-topic-boards) which is basically the same thing.

In all cases, the exposed information for a project is not enough. At the very least it should have a code and a creation date, and allow filtering and pagination.