Creating a delightful developer experience is really, really difficult to do and the team at Dropbox has done just that. The reason their developer experience is so great is because of a well planned and executed API Developer Journey.
An API developer journey is a path taken by a developer that results in successful software integration. It includes the following:
- Discovery of product offering and value proposition
- Developer registration and acceptance of terms
- API key creation and configuration
- API calls through code
- Integration testing
- Product release
- Integration maintenance
Let’s take a look at the Dropbox API developer journey.
1. Discovery of product offering and value proposition.
The first thing that a developer needs to understand is the product offering of the API. Dropbox addresses this on the Developer home page. Check out the following screenshot of the homepage.
The product offering is clear. I can either use “Drop-ins” for a quick integration into my software or the Dropbox “Core API” for more in-depth access to reading and writing files in Dropbox. I can also manage Dropbox for Business info with the Dropbox for Business API. The page is simple and the graphics are nice. Hyperlinks allow me to click through to learn more.
Why would I want to use these products? Because hundreds of millions of users already use Dropbox. That’s powerful.
2. Developer registration and acceptance of terms
The Developer experience is simply a part of the Dropbox website and integrates with existing end-user Dropbox accounts. I don’t have to register for yet another account. If I’m signed into the Dropbox website, I’m automatically signed into the developer experience.
If I am logged out, I hit the login page only when I attempt to visit the App Console for creating and managing my API keys. Everything else is made available to me without requiring the login. Delightful!
What about acceptance of developer terms and conditions? This comes later as a step when you register your app.
3. API key creation and configuration
Registering for an Dropbox API key is really easy. Simply go to the App Console and click on “Create app”.
From here, the app creation process is really easy. In fact, a wizard-like experience walks you through all of the steps.
The registration process walks you through a series of questions which in turn open up new questions depending upon the option that you chose.
The great thing about this is that you are only presented with questions that are relevant to the specific integration that you wish to build. You aren’t presented with a bunch of questions that are “optional” or irrelevant. This may seem like a small thing but all of these things add up to create a delightful experience.
The last step of the app creation process is the agreement to the Dropbox API Terms and Conditions. Again, Dropbox does a good job at making this part of the experience delightful. The Terms and Conditions document is actually really easy to grok. I’ve written more about this here.
The last thing to note about this experience is that the second time you come through the App creation process, you don’t have to re-agree to the terms and conditions. Leaving the checkbox in would have been the easy thing to do, but Dropbox values my time and doesn’t to waste it. Thank you!
4. API calls through code
Now that I have an API key, what’s next? How do I actually use this API? This is one of the areas where the Dropbox API really shines—the documentation and SDKs.
Dropbox has provided great SDKs for all of the most popular programming languages. The first thing a developer sees when going to the documentation is a selection of SDKs in each of these languages. Once you click into a programming language (like Ruby), the website remembers your language preference and caters the experience to a Ruby programmer. Brilliant!
It is tempting for providers of REST services to think that all developers have access to HTTP libraries and should know how to make HTTP calls and to parse and create JSON. Why would I need to provide SDKs?
There are a couple of reasons to provide good SDKs:
- While it may be true that a growing number of developers understand HTTP well, many developers don’t. You will be servicing a wide range of developer skill. You will notice that Dropbox never presented a “You must be this tall to ride” sign anywhere. Providing tools and sample code will help those that aren’t experienced HTTP developers to get started and be successful quickly.
Even for those developers who are HTTP and JSON parsing ninjas, providing a good SDK saves them time, and that is one of the developer’s most important commodities. A good SDK should have some robustness built into it so that it handles things like throwing appropriate errors, handling multiple types of configuration, etc. There is significant work here and making every customer re-invent all of that code is rude.
The Dropbox API developer journey guides developers through a path that will help them successfully install and configure the SDK, walks them through a tutorial including sample code, and then takes them to the meaty documentation that describes every possible API call. Here is a high-level flow of this journey:
Dropbox has remembered to generate and host the JavaDoc, RDoc, PHPDoc, etc. for all of the SDK libraries. Often, SDK libraries will simply post the code and hope the consumers of the code feel comfortable digging through the actual code to learn what is available.
Even further, the HTTP documentation links to individual method calls within the generated SDK doc for each language. Check this out:
So cool! I’ve been given all of the online support I need to successfully make my first Dropbox API calls.
5. Integration testing
When you create your API key, Dropbox puts your key into a status called “Developer” this puts certain limitations on the key such as the number of users that can use the key. The configuration does point to their production environment, so you are working with the real deal.
But isn’t developing and testing in production dangerous? Potentially, yes. However, your configuration options can sandbox your Dropbox access to a specific folder so that it keeps your file access and updating to a solidified folder. These controls keep you from accidentally doing something too destructive to your other important Dropbox files. It’s like a safety mechanism that keeps you from cutting your fingers off.
6. Product release
Once you have developed your code and it is ready for release, you simply navigate to your app within the App Console and click “Apply for Production”:
I haven’t completed this full process yet, so I will have to write more about it later. However, I have a pretty good idea of what to expect. If I read through the Terms and Conditions document, it referred me to the Developer Guide which clearly outlines how to gain Production Approval.
7. App maintenance
When reading the HTTP documentation for the Core API, it describes how the API will evolve. It basically says that the API will evolve in ways that it deems as backwards compatible—only adding new data or parameters but not changing existing behavior.
“This API will evolve. Future versions of this API may add new endpoints or parameters. In order to keep older clients working, the behavior and return value of APIs with given parameter values will not change from the currently documented behavior and return values, with two important exceptions: currently undocumented request parameters (whether they are actually ignored or not) may be given a specific meaning, and objects returned in responses may contain additional keys in the future.”
Core API – endpoint reference – Dropbox
Even with that statement, it looks like Dropbox has put versioning in the URL (/1/). Whether this technique is good or bad has been debated forever. I’m personally inclined to say that versioning is better handled via an HTTP header, but there are pros and cons to each approach.
One other thing to note is that from the Developers homepage, there is a feed of “What’s new”. It contains announcements regarding the API. When you click through, you discover the Dropbox Developer Blog. This provides you a way to subscribe to future news (email, RSS, Twitter, etc.). Way cool.
A winning experience
Dropbox delivers a fantastic API experience. Everything flows so well. It’s no wonder that there are 300,000+ apps integrated with Dropbox.