GraphQL global ID migration update
All newly created GraphQL objects now have IDs that conform to a new format, which we refer to as “next IDs.” Learn how to migrate older IDs to the new format and why we’re making the change.
![](https://github.blog/wp-content/uploads/2021/04/Blog_ENGINEERING_for-social.png?resize=1200%2C630)
We are pleased to announce that we have now completed the first phase of rolling out the new GraphQL global ID format. This means that all newly created GraphQL objects have IDs that conform to a new format, which we refer to as next IDs. It also means we’ve hit a major milestone as we work towards improving our scalability and speed. In this post, we’d like to give you some details as to how you can begin migrating to the next format for older IDs.
Why is this necessary?
The current format of Global IDs in our GraphQL API will not support our projected growth over the coming years due to limitations with the data encoded in the IDs. The next format gives us the ability to handle your requests even faster by being able to build queries that will be optimized for our database clusters. We will continue to support the legacy IDs for the short term, after which we will sunset them. We are asking that you use the provided tools (more on that below) to migrate your implementations, caches, and data records to reference a next ID for older objects. Doing so will ensure that the response times of your requests will remain consistent and small. It will also ensure that nothing in your application will break once we finally sunset usage of the legacy IDs.
Do I need to do anything?
You only need to react to this announcement if you store references to GraphQL IDs, which always correspond to the id
field for any object in the schema. If you don’t store these, then you can continue to interact with the API with no effect on your service. If you currently decode IDs, your service may break as the underlying data format of the IDs has changed. We suggest you migrate your service to treat these IDs as opaque strings. We guarantee the IDs will be unique, therefore you can rely on them directly as references.
How do I migrate my service?
If you have determined that you do need to migrate your service to the next IDs, we have introduced new functionality to help you do so. You can now pass a header in your API requests to the GraphQL API to receive updated IDs. This header works by forcing the response payload to always return the next ID for any object in which you’ve requested the id
field. The name of the header is:
X-Github-Next-Global-ID
This header can be set to two values, 1
or 0
. Setting the value to 1
will force the value for all id
fields in your query to return the next ID format. Setting the value to 0
will revert to default behavior, which is to show legacy or next IDs depending on their creation date.
Here is an example request using curl:
$ curl \
-H "Authorization: token $GITHUB_TOKEN" \
-H "X-Github-Next-Global-ID: 1" \
https://api.github.com/graphql \
-d '{ "query": "{ node(id: \"MDQ6VXNlcjM0MDczMDM=\") { id } }" }'
And the response will contain the next ID:
{"data":{"node":{"id":"U_kgDOADP9xw"}}}
The legacy ID of MDQ6VXNlcjM0MDczMDM=
was used in the node
query, and the response contains the ID in the next format. Using this mechanism, you will be able to call the API with the legacy IDs you have referenced in your application. The next ID received in the response can then be used to update those references. We suggest that you update all references to legacy IDs and use them for any subsequent requests to the API. Remember that you can submit multiple node queries in one API call (using aliases) to perform bulk operations.
Another option for migrating IDs would be to use the id
s returned in the nodes
field for a collection of items. For example, if you wanted to convert all the repositories in your organization, you could do something like the following:
{
organization(login: "github") {
repositories(last: 10) {
edges {
cursor
node {
name
id
}
}
}
}
}
As long as you have a reference to the name
of a repository (or some other unique field on an object), you could use this method to update your references in bulk.
Please also note that setting the X-Github-Next-Global-ID
to 1
will affect the return value of every id
field in your query. This means that even when you submit a non-node
query, you will get back the new format ID if you requested the id
field.
Tell us what you think
If you have any concerns about the rollout of this change impacting your app, please contact us and include information, such as your app name so that we can better assist you.
Tags:
Written by
Related posts
![](https://github.blog/wp-content/uploads/2023/10/Collaboration-DarkMode-2.png?resize=400%2C212)
2024 is the biggest global election year in history. What’s at stake for developers?
GitHub is considering what is at stake for our users and platform, how we can take responsible action to support free and fair elections, and how developers contribute to resilient democratic processes.
![](https://github.blog/wp-content/uploads/2023/10/AI-DarkMode-2.png?resize=400%2C212)
GitHub named a Leader in the Gartner first-ever Magic Quadrant for AI Code Assistants
This year, as part of its annual Magic Quadrant series, Gartner published a first-of-its-kind report analyzing the state of play in the AI Code Assistants market–and named GitHub a Leader.
![AI in software development 2024 survey results with colorful graphics and percentages.](https://github.blog/wp-content/uploads/2024/08/ai-survey-header.png?resize=400%2C212)
Survey: The AI wave continues to grow on software development teams
We surveyed 2,000 people on software development teams at enterprises in the U.S., Brazil, India, and Germany about the use, experience, and expectations around generative AI tools in software development.