Per UX review ( @steren @qelo ):

The API allows an N:N relation between Services and {Archetypes, Revisions}. This can be confusing to users and can be difficult to represent in user interfaces. Broken down:

N-1:

• one Archetype can be used by multiple services,
• a Revision can be referenced by multiple services.

Why is this a problem for the UI? The desire in the UI is to start with the main Services view and make things accessible from there, e.g. inside a service you see its revisions etc. However, this hierarchy is a lie compared to API and this creates incompatibilities and issues, e.g.:

Let’s say I have an Archetype without a Service (created via API or whatever) -- where in the UI I could see it? We would need a new “Archetypes” view, separate from our main “Services” view, which could be distracting to customers.

Let’s say I want to show details of a particular Revision. Assume the user got there from service X. I’d like to show the Revision in the context of X, and just say that the Revision is serving 50% for X, or is accessible at this URL etc. However, to fully show Revision details, the UI would need to determine that the Revision is also serving for unrelated service Y, or is routable with a different URL for service Z. This is magnified if you can reach the Revision from other paths, such as Archetype view or a Revision list view.

When a customer drills down to a Service, they want to be able to see a list of Revisions related to this service. If N:N relationships are present (and it can be difficult to determine if that is the case without a full list of resources in the namespace), it is difficult to suggest a query to find the relevant Revisions.

1-N: A service can use multiple Archetypes. This is another source of complexity:

We expect that the UI displays a single list of revisions (probably sorted by creation date). If these Revisions have been created by different Archetype, then displaying a single list might not map to the mental model of our users (they might consider them to in fact be multiple independent histories). Displaying multiple revision lists for a given Service complexifies the UI.