Community Announcement 📢: Deprecation of GraphQL API Endpoints

Making Speckle
, ,
1

Dear Speckle Community,

As one of the final parts of our “The Great Rename” initiative, we announce the deprecation of several GraphQL API endpoints. This initiative follows our successful migration from the legacy web application to the new platform, ensuring feature parity while gradually refining the underlying architecture.

Kudos to @fabians for your outstanding work in making this transition possible!

All endpoints will remain active for the foreseeable future to give developers ample time to migrate their apps, scripts, and custom connectors to the new terminology. While this isn’t technically a breaking change, as the endpoints will stay live for now, there isn’t a timeline for their removal. We strongly encourage all developers to migrate as soon as possible to avoid being caught short.

image
image875Ă—152 6.92 KB

In addition to mapping new terminology equivalents, we have extended the API terms, fields and subscriptions and will introduce more documentation about using some of these new features. We will also include more granular documentation on how to use the GraphQL API in general.

The Speckle Connectors team (thanks to @Jedd, @AlanRynne and @Kateryna ) has been upgrading all the Speckle SDKs to use the new verbs and queries. If you use those for server interoperability, you can continue using the wrappers and helpers without changes.

Additionally, the GraphQL explorer found at https://app.speckle.systems/explorer and the https://app.speckle.systems/graphql endpoints will include deprecation notices that recommend the new alternatives where there is a mapping to the new terminology.

NB - not all mappings to new terminology are direct translations where we have improved the semantics and logic to be more internally consistent.

.
Example Query notice

image
image1130Ă—132 9.71 KB

Example Subscription notice

image
image1128Ă—178 14.4 KB

Example Mutation notice

image
image1128Ă—174 13.5 KB

We appreciate your understanding and cooperation as we transition to this refined architecture. This change aims to improve clarity and consistency in our API. Please refer to the updated documentation and tutorials for guidance on migrating to the new terminology.

:hammer_and_wrench: Deprecation Details:

Query Type:

  • Deprecated fields include: streamAccessRequest, apps, comment, comments, stream, streams, discoverableStreams (:x: no plans to reintroduce), userPwdStrength, streamInvite, streamInvites.

Mutation Type:

  • Deprecated fields include: streamAccessRequestUse, streamAccessRequestCreate, branchCreate, branchUpdate, branchDelete, commitCreate, commitUpdate, commitReceive, commitDelete, commitsMove, commitsDelete, objectCreate, streamCreate, streamUpdate, streamDelete, streamsDelete, streamUpdatePermission, streamRevokePermission, streamFavorite (:x: no plans to reintroduce), streamLeave, streamInviteCreate, streamInviteBatchCreate, streamInviteUse, streamInviteCancel.

Subscription Type:

  • Deprecated fields include: branchCreated, branchUpdated, branchDeleted, commitCreated, commitUpdated, commitDeleted, userStreamAdded, userStreamRemoved, streamUpdated, streamDeleted, projectFileImportUpdated.

Stream Type:

  • Deprecated fields include: pendingAccessRequests, activity, blobs, blob, commentCount, commits, commit, branches, branch, object, fileUploads, fileUpload, webhooks.

User Type:

  • Deprecated fields include: activity, timeline, commits, streams, favoriteStreams, totalOwnedStreamsFavorites.

LimitedUser Type:

  • Deprecated fields include: activity, timeline, commits, streams, totalOwnedStreamsFavorites.

Branch Type:

  • Deprecated fields include: activity, streams.

Commit Type:

  • Deprecated fields include: activity, commentCount.

Object Type:

  • Deprecated fields include: commentCount.

PendingStreamCollaborator Type:

  • Deprecated fields include: streamId, streamName.

The activityStream is the last area we are working on.

3 Likes
2

I wanted to clarify the difference between the /graphql and /explorer endpoints, especially in the context of the recent deprecation announcement.

/graphql Endpoint: The /graphql endpoint is the primary access point for making GraphQL queries and mutations. This is where your applications, scripts, and connectors will send their requests to interact with the Speckle server. It’s designed for direct API interaction and is what you’ll use programmatically to integrate with our services. Additionally, the /graphql endpoint features a form of the Apollo Studio graphical UI, which is very powerful. This UI allows you to build queries by interrogating the documentation (found by clicking the docs icon ) and clicking on terms and fields to add them to the query. However, when using this endpoint, you must manually add authorisation headers to your requests.

Displaying the API docs

image
image718Ă—223 30.5 KB

Setting an Authorization header

image
image1748Ă—201 11.1 KB

/explorer Endpoint: The /explorer endpoint, on the other hand, is a user-friendly interface for exploring and testing GraphQL queries and mutations. It’s a GraphQL playground that allows developers to write and execute queries in an interactive environment. The explorer provides a graphical interface to help you understand the schema, inspect fields, and see live responses. It is an approved application, meaning it will automatically add authentication headers for you. This makes it a fantastic tool for debugging, learning, and experimenting with the API without needing to handle authentication manually.

Deprecation Notices: Both endpoints will display deprecation notices for the affected fields and types. We encourage you to fully use the /explorer for testing and understanding the changes while continuing to use the /graphql endpoint for your production applications.

2 Likes
3