Appreciate all the comments and saw there was a few similar questions so answering them all here.
GraphQL and Forge/Connect:
GraphQL APIs are indeed currently only available via Forge. The reason for this is purely a technical one with how Connect auth/scopes are handled. Support for Connect is being looked into, but we do not have any timeline related information to share.
GraphQL and Scopes:
Great question about this. This is where the power of graphql comes into play. With the REST APIs, the scopes can only be set at the path level. Thus anything that can be fetched with that path, must be part of the scopes for that path regardless if it’s actually fetched.
GraphQL via the Atlassian GraphQL Gateway has been configured in a way where scopes can be applied at the type level. This is extremely powerful because it means scopes can be tailored to exactly the query an app is trying to run - not just some top level generic ones based on the possible data being fetched. Trying to fetch a page and just get its title? Use just the page scope. Want to then also fetch its space? You’ll also then need the space scope - it wasn’t required before this.
Even with V2 REST APIs scopes will continue to be at the path level only.
@riku thanks for showing us your use case in such detail.
Our current thought process on labels is this:
Labels are a great example of something that is currently an expansion, that does not necessarily need to be an expansion in the V2 APIs. We understand that people often use labels as filters, so we will make sure to support this use case. Meaning, we will not require you to get every piece of content, and then fetch the labels in a separate call. We will make sure the list returning endpoints appropriately accept labels as a filter, and most importantly, we will work to optimize and make sure these can run a lot faster than the current queries.
You bring up another point we are looking to address, which is createdBy. While currently this is on the history / version which requires an expansion, we believe a field like this is core to the data itself. So for these types of items, we’d like to bring these up to being top level fields next to the other fields like title, space id, and so on. Therefore no expansion would be needed for these.
Page tree is a bit trickier and depends on whether the page tree is actually needed or just all of the content under a page / within a space. The latter being much faster.
Our goal is to make it so that we find a healthy balance between resources being properly scoped to their respective endpoints, and not unnecessarily increasing the number of calls required.
We have not yet investigated the search returning endpoints and how they will work in V2 APIs. You raise a good point which we would have to consider once we tackle them.
The GraphQL APIs are more of an alternative to the REST APIs. Both will offer search functionality that should accept CQL.