Building Your API for Longevity

by Mike Stowe

The video "Building Your API for Longevity," presented by Mike Stowe at RubyConf 2014, addresses the essential strategies for creating APIs that endure through time. Stowe emphasizes that developing a long-lasting API is not merely about coding but involves thoughtful planning and design. Here are the key points discussed in the video:

API Longevity Challenges: Stowe acknowledges the common difficulties experienced with APIs, including frequent breaking changes and backward compatibility issues. These challenges highlight why planning for the long term is vital.
Adopting a Long-Term Mindset: It's important to plan for the future instead of just reacting to immediate needs. Understanding the purpose and the audience for the API is essential.
Spec-Driven Development: Stowe promotes creating a clear specification before coding. This ensures a standardized design approach that facilitates collaboration and consistency among developers.
Understanding Users: Developers should engage with end-users throughout the API development process to ensure that the API meets their needs. A failure to do so can lead to wasted resources.
Backward Compatibility: Breaking existing contracts with API users incurs a cost and can hinder developer trust. Developers need to avoid making incompatible changes unless absolutely necessary.
Consideration of Future Needs: APIs should be designed with future requirements in mind. Stowe warns against focusing too heavily on current needs without anticipating future evolutions.
Versioning Strategy: API versioning should be utilized only when essential changes occur that break backward compatibility. Over-relying on versioning complicates API management and risks developer confusion.
Feedback Loop: Prototyping and gathering user feedback are crucial before launching an API, as these steps help prevent inconsistencies that could lead to a lack of adoption.
Best Practices: The talk concludes with a call to adopt best practices and to build APIs that are flexible and adaptable to change. It’s critical that developers think about long-term impacts while implementing short-term solutions.

The main takeaway from Stowe's presentation is that careful planning and a focus on user needs are key to developing APIs that remain valuable over time. Creating a successful API is about more than just coding; it's about building a reliable contract with users that endures through changes and developments in technology.

00:00:18.359 This is the talk about building an API for longevity. If you're not here for that talk, you're in the wrong place. Quick disclaimer: I don't know how to work tech. This is not a talk about how to code your API. If you're looking for framework usage or coding specifics, there are great tools out there, and Rails API is one great framework.

00:00:32.599 Today, we're actually going to talk about the key concepts you need to consider to build a successful API for the long term. A little about me first: I'm an API fanatic; otherwise, I wouldn't be giving this talk. I've encountered various problems with APIs.

00:00:49.120 How many people here have used an API? Hypothetically, how many of you have used a giant social media network API that seems to break every two months? Is that fun, or is it annoying? I see some people laughing; yes, most of us have that experience.

00:01:02.160 The other thing I want to point out is that I'm in Dev relations with Moft. I want to thank Moft for enabling me to be here. Moft deals with enterprises and serves about 30% of the Global 500. So, when we talk about best practices and the challenges of API longevity, these aren't just theoretical ideas; they are practical insights we share with large companies.

00:01:27.159 We all already know that APIs are changing the world. Today, there are over 13,000 public APIs. And the best part is that this number doesn't include all the mobile APIs, enterprise APIs, or network-to-network APIs; it only counts public APIs. There are hundreds of thousands of APIs out there, powering and connecting various devices.

00:01:53.280 Think about it: everything is becoming connected through APIs! Your home security system, for instance, will soon be able to communicate with your car, advising you on traffic as you leave work. However, to ensure that the Internet of Things (IoT) operates seamlessly, APIs need to remain persistent.

00:02:29.160 One critical aspect of API longevity that we often overlook is versioning. Making changes to an API can be very expensive, not only for the company but also for developers who have to migrate to a new version. Today, we will discuss five simple concepts that you can use to build APIs that last.

00:03:05.760 The first concept is to adopt a long-term mindset. It might seem like a no-brainer, but planning for the future is essential. You can't just think, 'I'll version it when I need to make changes.' If that's your mindset, you're unlikely to succeed. You also need to understand what you're building and why you're building it.

00:03:59.400 Utilize something called spec-driven development, which we will discuss further. Following best practices and repeating these steps again and again is crucial. Think of your API as a contract; put versioning aside for a moment. How many designers are in this room? It's important to think through the design. You can either pay a little now to design properly or a lot more later due to issues that arise.

00:04:44.280 Your API is essentially a contract. When you use a social media API and it breaks, what's your first thought? Likely frustration. Now, consider if that API were critical to your business. If you break backwards compatibility, you're telling developers that what they were using may not always work anymore. This not only costs them time but also detracts from their focus on building new features. Hence, it’s vital to avoid breaking backwards compatibility unless absolutely necessary.

00:05:37.639 You need to examine every aspect of your API: Who is it for? How will users interact with it? What are your plans for support? These considerations are critical, even though we won’t delve deeply into them today. One of the most important things you can do is find a management tool or API proxy, whether you build your own or use a service.

00:06:08.440 I’m with Moft and we are an API management provider. But I want to emphasize that it doesn't have to be Moft; you have other options such as Mashery, Three Scale, Layer 7, or IBM. The key point is to find a solution that meets your needs and provides that layer of protection for your API.

00:06:45.080 As you construct your API, consider who your end users are. Are they current customers, business partners, or third-party services? It’s easy to forget to engage in dialogue with your clients during the development process. I had an experience where we spent six months creating an impressive API, and after its launch, we realized no one was using it because it didn’t meet their needs. Subsequently, we wasted three more months trying to fix it, and ultimately had to scrap it.

00:07:19.800 This underscores the importance of understanding who you are building for and what they want to accomplish with your API. When big companies approach us to build APIs, we ask them what their goals are. Often they don’t have a clear answer. You’d be surprised how many companies cannot articulate what they intend users to do with their data.

00:07:51.960 Consequently, it’s essential to list out the actions you want users to take with your API. For developers, a critical piece of advice is to build only what is necessary. When creating your first version, focus on a solid foundation. Avoid the temptation to overcomplicate things; it's crucial to not reinvent the wheel or create your own specifications prematurely.

00:08:37.560 Instead, focus on what users need and want to do with your API. Are you building a REST API, or something else? It's vital to understand this choice: if you’re working with large legacy companies, they may be familiar with SOAP libraries. In some cases, using a SOAP API may be necessary, but ensure you understand what the decision entails in terms of usability and longevity.

00:09:43.360 You shouldn't default to REST just because it’s popular; you need to understand its advantages and principles fully. For many, APIs are, unfortunately, not RESTful. It’s essential to realize that if your API does not include hypermedia, it doesn’t adhere to REST principles.

00:10:59.640 We must also think beyond the immediate future when designing APIs. It’s a mistake to only consider what the API needs to accomplish today without accommodating future features. Expect unexpected requirements.

00:12:27.400 Dr. Alan Kay noted that we excel at short-term design but often fail at long-term design. I want you to reflect on your earlier code: Is the best code you ever wrote still relevant now? We need to proactively design for longevity instead of reactive changes.

00:13:06.520 One of the common misconceptions is the ease of versioning. Instead of opting for versioning as a solution every time a change is needed, recognize that doing so complicates matters. Backwards incompatibilities arise, and maintaining multiple versions confuses developers. I used to work at Constant Contact, and upon launching our API, we realized the complexity of having to support multiple systems. Developer adoption becomes incredibly challenging under these circumstances.

00:14:38.960 You should only plan to version your API when necessary, specifically when there are significant, backwards-incompatible changes. API versioning is not an easy way out; it should not excuse poor design.

00:15:33.679 For instance, we created an API without properly assessing its future viability, and soon we had to discard it, wasting hundreds of thousands of dollars in the process. You can do the right work upfront or pay heavily in the long run; there are no shortcuts.

00:15:57.040 Consider adopting the practice of spec-driven development, where you define your API before writing any code. It helps ensure that design is standardized, normalized, and uniform across the entire API.

00:17:05.200 Prototyping and getting user feedback are crucial steps before moving into development. This approach prevents the kinds of inconsistencies that render APIs unmanageable over time. Remember, most APIs don’t fail because of bad code; they fail due to design inconsistencies.

00:18:07.960 Having a well-defined spec allows for smoother collaboration among developers. Rather than having multiple developers potentially diverging from the intended API design, you align all efforts with a single documentation standard, enhancing efficiency.

00:19:16.679 When adding new features, maintain a long-term mentality. You should follow the same design, prototype, and feedback process each time to ensure consistency and sustainability. It's easy for developers to overlook long-term impacts when short-term changes seem simple.

00:20:20.879 Your API longevity relies on thoughtful design and practice, recognizing that one small change can lead to significant repercussions.

00:20:36.919 The secret to API longevity is not just adhering to best practices. You can implement every best practice and still fail if you don’t consider long-term implications when designing your API.

00:21:19.560 Once your API is live, it cannot be modified, which underlines the importance of careful planning at the outset.

00:21:51.640 I encourage you to leverage spec-driven development, whether you use RAML, Swagger, or other frameworks. Employ best practices, make the API flexible, and ensure you accommodate changes in various parameters.

00:22:34.120 You can find more information and resources in Moft's best practices series, which delves deeper into these principles.

00:22:50.720 If you've enjoyed this presentation, I would appreciate any feedback, positive or negative. Your responses are valued, and I’m open to discussions about any aspects you may dislike.

00:23:36.040 At Moft, we aim to help Enterprise companies implement these vital best practices. We’re launching a private beta program where you can earn rewards by learning about best practices in APIs.