Jimmy Zimmermanhttp://jimmyzimmerman.com
APIs, Family History, Star Wars, and Other Random WritingsFri, 08 May 2015 14:01:34 +0000en-UShourly1https://wordpress.org/?v=4.4.5Why the Dropbox developer experience is so delightfulhttp://jimmyzimmerman.com/blog/2015/05/why-the-dropbox-developer-experience-is-so-delightful.html
Fri, 08 May 2015 14:01:34 +0000http://jimmyzimmerman.com/?p=905Continue reading "Why the Dropbox developer experience is so delightful"]]>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.

]]>Evaluating the Dropbox API – Terms and Conditionshttp://jimmyzimmerman.com/blog/2015/04/evaluating-the-dropbox-api-terms-and-conditions.html
Fri, 24 Apr 2015 14:19:36 +0000http://jimmyzimmerman.com/?p=892Continue reading "Evaluating the Dropbox API – Terms and Conditions"]]>One of the first things that a developer encounters when signing up to use an API is the Terms and Conditions. While I don’t enjoy reading legalese, there are some things that I appreciated when reading the Dropbox Developer Terms and Conditions document.

A Friendly Tone

“Thank you for developing on Dropbox!” This is opening statement of the terms and conditions document. Wow! Dropbox wants me to develop and the terms and conditions document doesn’t simply exist as a threat to sue me. It is welcoming and invites me to explore further.

“Please carefully read these Developer Terms before investing your time in using the Developer Platform.” This tells me that Dropbox cares about my time as a developer. They don’t want me to waste my time developing something that cannot be released because I’ve inadvertently violated the terms of use.

Readable by an Ordinary Human

I appreciate that the terms and conditions document is readable by an ordinary human. I don’t have to hire a lawyer to understand what I can or cannot do. Thank you!

Developer Guidelines

The terms and conditions document links to a different document called “Developer Guidelines” that gives specific development guidance on how to make it through the production approval process. That document is concise, explains the process to obtain approval, and clearly outlines the things that they encourage and the things that they don’t allow. This is helpful because it is clear to me what I need to do to successfully navigate the Dropbox app review process. Dropbox is focused on my success.

Acceptable Use Policy

The terms and conditions also link to a document titled “Acceptable Use Policy.” This document clearly defines the things that you are strictly prohibited from doing. This is like the Dropbox commandments and defines the behaviors that they define as nefarious.

If you don’t have this defined, well-meaning developers will do all sorts of creative things with your site, including reverse engineering your website software, discovering private APIs, and causing havoc.

Stating the rules is a good thing. Good developers would rather know the rules of engagement up front than be yelled at later through some sort of cease and desist communication.

Of course, an acceptable use policy won’t have any effect on black hat developers as they will do whatever they please. You must have appropriate security measures in place to protect your system, and this goes beyond your API.

End User Data & Information

“If you collect data or information from or about users (“User Data”) via your Dropbox Developer App or the Developer Platform, you must ensure that it is collected, processed, transmitted, maintained, and used in compliance with all applicable laws, industry standard security practices, and a privacy policy that you post and make clearly available to users.”

As a potential consumer of the API, I appreciate that Dropbox doesn’t dictate what my security practices must be. I just need to be smart and follow industry standard security practices, which I should do regardless.

Enough!

Blogging about a terms and conditions document is boring, but a great developer experience requires attention to detail at every touchpoint. Dropbox has done a great job here.

Grade: A

]]>An API a Dayhttp://jimmyzimmerman.com/blog/2015/04/an-api-a-day.html
Thu, 23 Apr 2015 18:49:03 +0000http://jimmyzimmerman.com/?p=884Continue reading "An API a Day"]]>I’ve been working with REST APIs for about 8 years either as a consumer or as an API publisher. My current employer, FamilySearch, has a pretty extensive API that is used by many companies. This year, we are really focusing on how to improve the developer experience so that developers can more easily grok what we offer and can quickly and easily build an app that takes advantage of the powerful features of our API. Currently, there are many barriers that are preventing developers from being successful early.

Part of what we are focusing this year is on documentation and tools. My hypothesis is that if we offer really great SDKs with accompanying documentation and sample code, that developers will be able to consume the API much more quickly and will have a pleasant developer experience.

I’m constantly looking for other companies that offer great developer experiences and evaluating the success factors that create a great developer experience. This is the beginning of a journey that I plan to document in looking at many developer offerings. I’ll call this series “An API a Day” even though I fully understand that I can’t possibly analyze an API every day.

Here are some of the developer platforms I plan to analyze:

Dropbox

Twilio

Box

Evernote

Twitter

Facebook

Stripe

This list will grow in time. My first stop will be Dropbox.

What other companies should I add to the list?

]]>MooseRoots Record Embedshttp://jimmyzimmerman.com/blog/2015/02/mooseroots-record-embeds.html
Tue, 03 Feb 2015 22:36:12 +0000http://jimmyzimmerman.com/?p=873Continue reading "MooseRoots Record Embeds"]]>This is cool. MooseRoots.com has embed/share code to embed a number of their visualizations on your blog or website. check this out:

]]>Apple’s Copy Crushhttp://jimmyzimmerman.com/blog/2014/06/apples-copy-crush.html
Tue, 03 Jun 2014 13:34:31 +0000http://jimmyzimmerman.com/?p=840Continue reading "Apple’s Copy Crush"]]>Apple’s WWDC 2014 keynote revealed some cool new innovative features for Mac OS X and iOS. It also showed off several features that simply copied from products built on its platform. In an attempt to dazzle developers with the new features, Apple sent the message, “We will copy your features and crush your apps!”

The new Spotlight is a near clone of the Alfred App. I have been a big fan and supporter of Alfred App, but as more of Alfred’s features get built into the operating system itself, there may be less reason for me to use and promote Alfred. Sad.

Some of the new iOS Mail features ripped off concepts from Mailbox. Long swipe to delete and swipe for reminder actions are powerful Mailbox features. I believe Mailbox still holds an advantage because its reminder system is superior to the iOS Mail reminder. Mailbox lets you choose when to be reminded. Mail simply flags the message.

Does Apple do itself a disservice by competing with its own app market? Does this make app creators nervous? Or should app writers always assume this risk?

]]>I’m (not) an SEO Expert!http://jimmyzimmerman.com/blog/2014/05/im-not-an-seo-expert.html
Thu, 29 May 2014 06:00:49 +0000http://jimmyzimmerman.com/?p=831Continue reading "I’m (not) an SEO Expert!"]]>Based on LinkedIn endorsements, my profile makes me look like I’m an expert in SEO. Perhaps this is because 7 years ago, I was doing a lot of stuff in the SEO world and it was one of my first skills recognized on LinkedIn. Today, I’m not an expert in SEO. I have a stale knowledge of how SEO worked 7 years ago with Google Page Rank, using the terms that you want to optimize consistently and naturally throughout your post content, making sure you mark up the key terms in headers, titles, etc.

I’m not an SEO expert nor do I really want that skill on my resumé. I guess need to spend some time on my LinkedIn profile so that it gives a more accurate representation of me. Update: I found a way to bury SEO down on the Skills & Endorsements section.

If you have worked with me recently, will you do me a favor and please endorse some of my more current skills (Account Management, Product Management, Family History, Genealogy)? Only do this if you think the skill(s) really deserve endorsement. Thank you!

]]>Genealogist.com—the new kid on the blockhttp://jimmyzimmerman.com/blog/2014/05/genealogist-com-the-new-kid-on-the-block.html
http://jimmyzimmerman.com/blog/2014/05/genealogist-com-the-new-kid-on-the-block.html#commentsTue, 20 May 2014 13:50:43 +0000http://jimmyzimmerman.com/?p=822Continue reading "Genealogist.com—the new kid on the block"]]>A web developer that I really respect, Nic Johnson, recently left FamilySearch to join Genealogist.com. I hadn’t heard of the company yet, so I signed up to be notified of launch. A couple of days ago, they notified me of an update to their homepage with a preview of what is to come. Here is my first impression of Genealogist.com.

Please note that any opinions expressed here are my own and don’t necessarily reflect those of my employer, FamilySearch.

Genealogist.com has an audacious goal of becoming “THE personal and permanent place for everyone…” I applaud the company for taking on such a noble cause. I have to admit that I’m a bit skeptical of the service’s permanence, but that may be an unfair statement at this point. 1000Memories.com had a similar claim of permanence, but when Ancestry.com acquired them, the website gave a notice that they would be shutting down the service and gave users a window of time to download their data. On the other hand, FamilySearch has a similar permanence goal, but has a long-term (permanent) funding commitment from the Church of Jesus Christ of Latter-day Saints as family history is a core part of its doctrine.

The design of the Genealogist.com is beautiful. The colors, typography, and images on the homepage are gorgeous. The design of their Lifepage looks very modern and engaging. It looks like they are incorporating many of the same features as the FamilySearch Family Tree such as Sources, Memories, Conversations, etc. It seems to focus more on the posting of short stories, audio clips, videos, etc. Perhaps this will help draw a younger crowd.

The marketing copy is fantastic. Just reading the content on the homepage makes me excited to see what is coming. The message targets more than today’s genealogy enthusiasts. Clearly, the company has assembled a very talented team of designers, writers, and engineers to launch this product.

It appears that Genealogist.com will be launching with a mobile strategy out of the gate. This seems necessary for any product that wants to keep users engaged with the product at frequent intervals.

I have questions about Genealogist.com that I hope to find answers to—eventually.

1. Ancestry.com, FamilySearch, findmypast, and MyHeritage have historical records that go with their tree services. They use the historical records to drive data into their trees. What is Genealogist.com’s historical records strategy?

2. How will Genealogist.com assure me of the long-term permanence of the service and data?

3. Is Genealogist.com pursuing a single, shared tree for all of humanity? Or will all users control their own individual trees? Or will there be a hybrid of sorts that bridges the two worlds?

4. Will Genealogist.com have an API? If so, will it implement the GEDCOM X RS specification? If it did, it could potentially pick up a lot of clients that have already integrated with FamilySearch’s platform.

I am in favor of more innovation in the family history field, so I hope for the success of new and existing companies. There are a ton of problems to solve and many audiences to reach. The genealogy industry is relatively small in comparison to other industries and it has largely been dominated by a few big players. I believe there is room for our industry to grow. This isn’t a zero-sum game and I’m optimistic that amazing things are around the corner.