We announced the Twitter API v1.1 in August 2012. Twitter itself has evolved a lot since then, as has our developer platform – with the addition of new services like our enterprise data APIs and the Ads API. Today, many of these developer services look and feel different from each other, and some valuable features are not available to all developers. Moving forward, we want to simplify our services for developers, make them easier to use, and make useful functionality available to more people. We know feedback from developers will strengthen our approach, which is why today we announced we are launching a new program called Twitter Developer Labs to let developers test new API endpoints and share feedback before we finalize our approach. This post explains some of our early thinking about key design decisions in the initial endpoints we’ll release.
Versioning, for real
Though we kept the Twitter API on v1.1 for a long time, we’ve changed it a lot through the years. For example, we doubled a Tweet’s maximum length. Rather than deprecating certain fields and behaviors, we introduced a new Extended Tweet object containing the full representation of an extended Tweet.
With v1.1 we chose to maximize backwards compatibility and limit the changes developers had to make, which created a natural tradeoff that resulted in increasing the complexity of navigating the growing payload of a response object. In practice, it’s been a good compromise, allowing many applications to work for years without changes, but it’s also created a few challenges:
- As the Twitter service has changed, we’ve had to deprecate fields and features.
- We’ve held back adding some features to the v1.1 API because they’re challenging to add to existing structures in a clean way.
- As we strived to maintain compatibility, API responses grew in size, and developers had to accommodate this – sometimes at great expense.
Designing a new version of the Twitter API gives us the ability to address these challenges and set the stage for a future versioning strategy that’s predictable and more responsive to the needs of our developer community. One of our top priorities for doing this work will be to provide clarity and a reasonable timeframe for developers to make any changes.
When it came to deciding how we might implement versioning in the API itself, we evaluated two approaches:
- Header versioning, where developers can make a versioned or unversioned call (if no version detail is provided, will default to the last available version). Versioned calls are made by providing a custom request header (e.g.
- Path versioning, where developers must specify a version as part of the endpoint URL (e.g.
Both methods have their advantages and disadvantages. We chose path versioning for the following reasons:
- It’s been our choice for existing APIs
- It’s widely adopted in the industry
- It’s easy to implement for developers
We plan to make a major version change within our Labs program after we launch – incrementing to a new Labs version once we have been able to incorporate developer feedback. As part of this, we’ll be testing out the practical impact of our versioning approach, and want developer feedback on making it easier to update to new API versions in the future.
New functions for REST endpoints
We’ve designed our initial Labs releases so that developers can minimize the number of calls they have to make, while still getting the data they need. This is a challenge GraphQL solves elegantly, though for now, we’ve chosen to stay with REST because it’s more familiar to most developers and better supported than GraphQL. We still took inspiration from certain aspects of GraphQL with our new expansions and selectable response formats.
An expansion allows a developer to request a full object from its ID. By requesting an expansion as a query parameter, developers can receive the relevant object in the response. This solves for both over-fetching (expand only relevant objects) and under-fetching (getting the data you need in one query).
A response format is a way for a user to specify the level of detail in a response. Take for example a
GET /labs/1/tweetsrequest. If you are primarily using the API to display Tweets, you can pass a
format=compactquery parameter to reduce the response object to the relevant fields needed for display. Likewise the
format=detailedquery parameter returns additional fields that we know are not used by all developers.
Response formats and expansions are complementary: you can request a detailed user object, while limiting a Tweet object to a compact format – all in the same request. If you need minimal details about a Tweet, but you still want to receive details about its author, you can pass query parameters such as
format=compact&user.format=detailedto fine-tune the granularity of the response object.
Piloting a formal specification
The long history of v1.1 API resulted in increasing complexity that has gotten in the way of developers, particularly those who are new to the Twitter API. In Labs, we’re approaching this problem by formalizing the behavior of our endpoints. We model an endpoint by defining allowed parameters and responses in a specification, and we use the specification as the source of truth for our implementation. Developers can expect a cleaner design, driven by principles we’ll define with their feedback. To do so, we’re using OpenAPI specs to define and expose behavior for each new Labs endpoint.
We’re also attempting to improve discoverability and exploration of the Twitter API by adopting a consistent specification format for our endpoints. We think OpenAPI can help us here too, since its specs use JSON Schema to specify response objects and data types. Going forward, this sets the foundation for an API platform that’s more predictable and intuitive.
We’ll release the first endpoints to all eligible developers in the coming weeks. If you’re interested in participating, there are a few things you can do today:
Visit the Labs website and sign up to receive updates when the first endpoints go live in the coming weeks.
Create a developer account (if you haven’t yet). Access to Labs will require a developer account, and an approved app use case, even if you have an active app created through the former
Review the Labs documentation to learn more about what’s coming.
Share feedback and let us know what you think.
With Labs, we intend to iterate on new ideas quickly and often. Since the endpoints we will release in Labs are early previews, they may change before we release them broadly. We encourage you to take that into consideration as you build with them. When we’re ready to release final versions of any new endpoints, we’ll give you advance notice, so you have time to make updates.
None of the decisions above are set in stone, and this is by design. We’re inviting interested developers, to partner with us as a community because we’re serious about ensuring that each developer who builds with us finds a voice in our roadmap and is set up for success to get started and grow. Do you like the direction we’re taking? Do you see areas we can improve? Do you have ideas for what we should build next?
We’ll roll out and test these features through our initial Labs releases soon, and you can keep abreast of new Labs products when you sign up for updates or follow @TwitterDev. In the meantime, let us know what you think using our feedback channel. And if you want to share your thoughts in person, or get a live update on Labs, our next #TapIntoTwitter developer community event is in New York on June 4. Stay tuned!