Apple is one of the biggest API platforms in the world — every app running on every iPhone and iPad is built using the Silicon Valley giant’s APIs. We can all develop a better API strategy by examining how one of the leading API platforms:

• Uses their own APIs within their own ecosystem;
• Handles changes to these services; and
• Prioritises end user experiences over other concerns.

During three excellent episodes of the iOS/OSX programming podcast, Debug, hosts Guy English and Rene Ritchie interviewed Apple veteran developer Nitin Ganatra. Nitin has been at Apple for many years and has worked on everything from System 7 to OS X to iOS. In the third interview, Nitin and the hosts talk about Apple’s views on APIs. The three were not discussing the kind of APIs we usually write about on Nordic APIs (i.e., web-based ones), but rather lower-level Objective-C APIs. Despite this, the interview does reveal a lot about Apple’s approach that we all can learn from as we build higher-level, RESTful APIs.

Tasty, Tasty Dog Food

In the initial release of the iPhone operating system, Apple used internal classes to handle operations like scrolling and tables in their own apps. These classes had good performance and were easy to use, but were available for Apple developers only. External developers did not have access to these classes, and instead had to use public APIs that Apple created for third-parties. These were harder to use and required tricks to get comparable performance. To make app development easier for these important stakeholders, Apple changed their apps to use the same classes as these external developers. According to Nitin this was done “.even though we knew that by doing that we were deliberately slowing down our apps.”

This “dog-fooding” of the public API forced Apple to improve the usability and performance of their outward interface. This type of testing echos recommendations given by other API providers like Fyndiq and PlanMill which we have shared before. Keep this in mind when you are developing apps on your own API. If you need a special API that is not available to external developers in order to build your app, that is a clear sign that something might be wrong with your external API.

End User Experience Matters Most

There is a lot of talk about Developer Experience (DX) in API circles. This is not surprising when you consider that developers are the consumers of APIs. When the API is the product, it is important to delight the customer with great experiences. What we cannot forget in these discussions, however, is that there is another very important stakeholder — the end users of the apps. In the Apple case that Nitin discussed, this is anyone with an iOS device. If an app stops working because the developer does not keep up with Apple’s API changes, for example, it is taken very serious by Apple, as Nitin explains:

Even in a case where a developer is knowingly not doing the right thing for one of their own customers, it’s still, to that customer, going to look like an Apple problem. You can still end up with unhappy customers, and that’s going to reflect poorly on Apple. We had to take that very seriously.

One of the hosts, Guy English, responded to Nitin’s explanation of Apple’s views by saying:

I think what’s interesting here is the way that you’re describing the end user of the software. A third party [developer] may see the person using their software as their customer, but Apple is seeing that customer as Apple’s customer. It is their duty to their customer that stops them from shipping APIs or making promises to third-party developers that they may not be able to keep. The intention is not to limit developers and the possibilities of developers, but the intention is to give the customers — the end users, the real customers — the best possible experience.

Guy’s summary points out that the goal with any API is to provide value. As with Apple, this value is not created when a developer uses the API. Rather, it comes when an end user consumes the app that developers have created with the API. Do not lose this perspective as you strive to create the best API you can. If you do, the API you make will have a great DX which in turn will help developers provide a fantastic end user experience.

Be Careful with Change

It is easier to change an app than to change an API because the stability of this interface is depended upon by many different apps which are implemented by different developers. As Guy English puts it in the podcast:

APIs are one of the hardest things to shift because you can always update an app to fix a problem. [With] an API, you’re stuck with it for probably far longer than you want to be.

Apple is known for being conservative with API changes, and they have good reason to be, as Nitin expresses:

You have to think about the next five plus years out when you’re implementing some of these things or developing these APIs, because, like [Guy] said, you’re going to be stuck with it for years. It comes from that hard-fought knowledge that every time something relatively simple has worked it’s way into an interface, or most of the times that you’ve tried to cobble over a problem with an API, or provide some new functionality by some “clever trick”, those are the things that are going to bite you in the ass hard in three years.

When an API is popular, there can be no such thing as breaking changes because such updates would impact so many developers and end users. This type of break places the focus on the wrong things. As discussed above, UX and DX trump API design. Changes will be needed, that’s for sure. When they are, however, make them very careful since their repercussions are hard to foresee and long-lasting. After just a couple breaking changes, how popular will your API be then?

Summary

From this interview with Apple, we can see that good APIs require us to:

• Focus on the end users experience;
• Eat our own dog food; and
• Be careful with changes.

This is not novel advice, but it is powerful in its simplicity. Hearing these priorities from a company with as much API experience as Apple is very compelling and noteworthy. For more, listen to the interview or read the full transcript yourself. Thank you to Debug for a great podcast and a big thank you to Nitin Ganatra for sharing!

If you have learned valuable lessons in your API project like these, please share them with us on Facebook, Twitter, or come speak at Nordic APIs Platform Summit in October.

[Editor’s note: Nordic APIs is an independent publication and has not been authorized, sponsored, or otherwise approved by Apple Inc.]