What is developer experience? And how can it affect the success of your product? Our very own Keshav Vasudevan will take you through everything you need to know.
4. Page
Proprietary & Confidential
The Multi Platform Ecosystem
A platform is a product that canbe extended by users for the benefit of others
Average consumer
Third party developer
4
6. Page
Proprietary & Confidential
Developers Are Humans Too
DX is the aggregateof allthe experiencesa developer has when interactingwith your Platform,usually
through an API
6
7. Page
Proprietary & Confidential
Why Developer Experience Matters?
Growth and Adoption: The value of anAPIincreases when users reachcriticalmass
PreventsSwitch: MakesAPIs differentiable and competitive
Helps drive business and technological goals
7
10. Page
Proprietary & Confidential
A DX Focus
Focusses on solving an actualhuman need
Focusses on driving the business
Focusses on sustainability
10
11. Page
Proprietary & Confidential
3 Step DX Framework
Recommended for optimizing the DX of your API
Step 1
Understand the API’s
audience
Step 3
Map the audience to the journey
Step 2
Understand the
audience journey
11
12. Page
Proprietary & Confidential
Step 1: Understand the API’s Audience
API Users
Newcomer -
First Time
User
Debugger –
addressing a
specific issue
Evaluator-
Deciding whether
to use the API
Problem Solver –
Is X possible with
this API
API Decision Makers
Eg: CTO Eg: PM
12
14. Page
Proprietary & Confidential
Step 3: Map Journey to the Right Audience
Why should I use
it?
How do I register? Where do I start? How do I use it?
Focus: Decision
Makers
Focus: Decision
Makers, API Users
Focus: Decision
Makers, API Users
Focus: API Users
Product Marketing Design and
Documentation
14
16. Page
Proprietary & Confidential
Before We Proceed…Follow the 3:30:3 Rule
Credit: OriPekelman
3:30:3 Rule
3 seconds to understand API’s purpose
30 seconds to identify entry point into system
3 minutes to use the API’s result
16
17. Page
Proprietary & Confidential
3.a. “Why Should I Use It”?
Focus:
Decision
Makers
Why should I
use it?
Position based on Industry Concise messaging of core
value
Understand value in 3
seconds
Recommendations
17
20. Page
Proprietary & Confidential
3.a. “How Should I Register”?
Focus:
Decision
Makers
Why should I
use it?
Explain setup in a
comprehensive fashion
Minimal steps to register –
30 seconds
Provide API console
Recommendations
Focus:
Decision
Makers, API
Users
How do I
register?
20
24. Page
Proprietary & Confidential
Example: SoundCloud
SoundCloud asks users to fill up a 3 page
Google form, with details on the app
idea, before awarding the API key.
Waiting period is typically 2 weeks
24
25. Page
Proprietary & Confidential
3.c.d “How Do I Use It”?
Focus:
Decision
Makers
Why should I
use it?
How do I
register?
Where do I
start?
How do I use
it?
Documentation
25
27. Page
Proprietary & Confidential
What is API Documentation?
• Describes how to be successful with the API
• Deliverable of technical writing
• Acts as the usage manual for the API
An API is only as good as its documentation
27
30. Page
Proprietary & Confidential
Major Problems
Maintaining documentation, tests and implementation was always hard
Implementation always cameatthe cost of DX
Communication betweenservicesbuilt in different languages was hard
30
31. Page
Proprietary & Confidential
RESTful Interface
Call the API
(request)
Obtain data
(response)
Restful
Interface
Technical
Writer
Developer Tester
Architect
Keeps in
Sync
31
32. Page
Proprietary & Confidential
The OpenAPI Spec is the API’s Contract
• The OAS is an API descriptionformat to Design and Document REST APIs
• The OAS defines the API’s contract
• Connects computers, technologystacks and humans in one language
32
36. Page
Proprietary & Confidential
3.c.d “How Do I Use It”?
Focus:
Decision
Makers
Why should I
use it?
How do I
register?
Where do I
start?
How do I use
it?
Documentation
36
37. Page
Proprietary & Confidential
Tips for Effective API Documentation
Tip 1: List the Fundamentals
Tip 2: Write for Humans
Tip 3: Explain your Request-Response Cycles
Tip 4: Empower with Experimentation
37
43. Page
Proprietary & Confidential
Tip 2: Write for Humans
NeverAssume
Audience is 100% developers Consumers are fully familiar with
API/Domain Jargon
• Strive to make documentation readable by Decision Makers
• Start writing in plain English without jargon
• Provide context and information for jargon and domain specific words
• Maintain consistency of tone
43
45. Page
Proprietary & Confidential
Tip 3: Explain Your Request-Response Cycles
• Your APIUsers should know exactlywhatto expectfrom a successful call
• Describe full sample response body in everysupported format
• Focus not just on the response format,but also HTTP response headers and error codes
• Provide enough context using examples
1. Examples in Use Cases
2. Examples in Request-Response Cycles
45
51. Page
Proprietary & Confidential
Summary
• Good APIDeveloper Experience can help drive business and tech goals
• Threestep framework for understanding API DX
• Understand audience
• Understand journey
• Map journeytoaudience
• Tips for Good API Documentation
• List the Fundamentals
• Write for Humans
• Explain your Request-Response Cycles
• Empower with Experimentation
51
We’re in the multi platform economy, and APIs are the digital glue that holds them together. What do I mean by platforms? Well, lets take an example of Facebook, or fitbit-
Facebook was started in 2004, and enabled people to make social connections and interact online. It was a product on the WWW and 3 years later, FB launched their API, to give an unprecedented amount of access to developers. , transforming FB from a product into a platform.
A platform is a product that can be extended by a user for the benefit of other users. Any product can become a platform by providing methods for users to add services and functionalities on top of it, and APIs has enabled products to become platforms more easily by connecting them together with APIs.
When a product transitions into being a platform, it takes on a new type of user: the third-party developer. But they are a special type of user, one that behaves as an intermediary between end users and the platform product.
As such, it is incredibly important to cater to the experience of the developer consuming your APIs, espeiclaly given APIs are actually driving business and technological goals.
Developer Experience is an extension of UX that focuses on the experience of the developer integrating and consuming your Platform
As with any product — and yes, APIs are products, the documentation is a usage manual for effectively consuming your API — we need to start by understanding who needs to use the content you produce. The most common form of consumers for your API’ documentation, are the people who need to directly integrate and work with your API, and the people who want to evaluate whether your API will fit into their development cycle and business strategy.
They are-
Engineers looking to get started — newcomer
Developer solving a specific issue in an existing client — the debugger
CTO evaluating competing APIs — the Evaluator
Product manager figuring out if X is possible with the API — problem Solver
1: Information Architecture
When designing site-wide information architecture, it is important to note the priority of what information the site visitor needs to know. One must consider what information developers immediately desire to see, and what resources visitors with varying levels of experience will require.
Providing detailed documentation is a must for a technical audience, and your non-technical audience will require information on licensing agreements, an often underprivileged aspect. Your structure should accordingly group relevant information into categories that are easily understandable and easy to find. It’s a good idea to order sections from the broad to specific, making sure that you have clear paths to the information, and a good search by keyword or topic option available.
As an example, take the MailChimp API portal. It prioritizes highly pertinent information with a reminder of v3.0 version release and deprecation notice. It also does a good job of structuring information in order of beginner to advance, ordering sections from Getting started —> How-Tos—> Downloads and API wrappers —> Actual API Documentation. Links that may be irrelevant to a bulk of site visitors, like Partner APIs, or MailChimp’s Mandrill service, are still included yet listed toward the bottom in accordance with priority.
http://nordicapis.com/beautiful-ui-design-for-api-developer-portals/
Mention how designers and documentation writers should partner with marketing
Once you’ve identified your audience, and their journey to using your API, it’s time to map what the main focus would be across each phase of this journey. This focus doesn’t mean you should ignore the other type of users, it only means you need to make sure that at a bare minimum, that this specific type of audience is catered to.
In the first stages we should, at a minimum, focus on the Decision Makers like the CTOs and PMs. The next two stages – which is “How do I register” and ‘Where do I start”, should cater to your API users as well as your Decision Makers. The remaining stages should have a strong focus on your API users, meaning these people should be able to have a great experience registering, understanding, integrating and consuiming your services.
These phases are also functions of different job types. For example, the first two stages is more of a Product marketing exercise, with effective messaging of your platform’s values. The next stages is a documentation and technical writing exercise, with rich content for a technical user base that enables them to understand how to use your API.
http://nordicapis.com/5-reasons-why-developers-are-not-using-your-api/
Ori Pekelman, a regular speaker at API events, created a rule that summarizes the best possible engagement between developers and your API. The 3:30:3 rule states that on the homepage of your API a developer should:
Be able to create an account, call and Understand in 3 seconds the purpose of your API.
Be able to identify the entry point in 30 seconds the system, and use the result in under 3 minutes
To be able to follow this rule you should treat your API as a product where developers are your target customers. Every piece of content you put out, be it on the homepage or in the documentation, should try to help your end users obtain the most value in the minimum amount of time possible.
The OAS is an API description format to design and document REST APIs. It can be written in YAML or JSON, and involves no code. It’s pure human and machine readable, and just designs what the API does and how it’s supposed to behave
To use the toolkit, you start by modeling your API with the Swagger(openAPI) specification, written in YAML or JSON.
Example contract – describe metadata, resources, operations.
Towards the end, say “keeps them all aligned and in sync”
In the context of this webinar, one of Swagger’s biggest strengths is the ability to generate interactive documentation straight from your API’s contract.
Most API docs just assume their audience is 100% developers, and further (incorrectly) that those developers are completely familiar with the API’s domain and jargon.
Instead, you should strive to make the documentation for every call intelligible first to the people searching (evaluators) , who are trying to understand which call does what to which nouns and why. I would recommend that you actually start your documentation process by writing these English domain explanations for each call. It is also a great practice to link jargon and domain-specific words to useful definitions the first time they are used in any given section.
These tactics will help you ensure clarity and good structure across your API at the level of the domain and why certain calls exist, before you ever get lost in the details of parameters, headers and responses.
Consider your overall tone — Your documentation should have a consistent tone, in tune with whatever branding strategy your company has adopted. Try to reflect this tone across every aspect of your documentation to help speed up the learning process
https://bradfults.com/the-best-api-documentation-b9e46400379a#.eroijicnl
Do not leave anything to the imagination with your request and response cycles. Your end users should know exactly what to expect when using any end point.
Think of not only the format, like XML or JSON, but also of the HTTP headers, error codes and messages. Put yourself in the end user’s shoes, and understand that too much information when integrating with your services is never a bad option. Describe the entire parameter and response body
You should also, in the start itself, describe all the possible error codes. I’ll show you an example of how Stripe handles this in the next slide.
When naming parameters, use terminology that users will understand. As always, provide examples of the type of parameters, a description and any other information you believe could help your end consumer
Do not leave anything to the imagination with your request and response cycles. Your end users should know exactly what to expect when using any end point.
Think of not only the format, like XML or JSON, but also of the HTTP headers, error codes and messages. Put yourself in the end user’s shoes, and understand that too much information when integrating with your services is never a bad option. Describe the entire parameter and response body
You should also, in the start itself, describe all the possible error codes. I’ll show you an example of how Stripe handles this in the next slide.
When naming parameters, use terminology that users will understand. As always, provide examples of the type of parameters, a description and any other information you believe could help your end consumer
Offer an API console: This is the minimum you should offer as an experimentation tool. With an API console, developers are encouraged to immediately test what they see in the documentation, and see real API calls taking place.
This interactivity is not just helpful for the API consumer, but it’s aslo great for the person doing the documentation
http://nordicapis.com/spark-api-adoption-good-documentation-practises/
A good option to provide a sandbox is to use some type of virtualization that lets your system quickly deploy a server that is ready to use by developers. There are several available options with varying levels of complexity:
Using Vagrant with an image containing your API server and a fake data set. Vagrant quickly launches a VirtualBox machine that can easily be shut down and relaunched.
Using Vagrant with a cloud hosting provider such as DigitalOcean. This option will make it even easier because you don’t have to deal with the servers yourself. There’s a great tutorial explaining how to get this setup and running.
Using Docker to quickly launch a new API environment that developers can access. A way to do this is to use Fig which lets you launch an isolated environment using Docker.
http://nordicapis.com/5-reasons-why-developers-are-not-using-your-api/