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.
