Downloaded 13 times
Uploaded bySmartBear
Executing on API Developer Experience
The document outlines the importance of a positive developer experience (DX) in API development and offers a three-step framework for optimizing DX by understanding the audience, their journey, and mapping this to documentation and marketing. It emphasizes the necessity of effective API documentation, which should be user-friendly, clear, and empowering. Additionally, it includes tips for documentation best practices to enhance the overall experience for developers and decision-makers engaging with APIs.
More Related Content
Similar to Executing on API Developer Experience
Executing on API Developer Experience
- 1. Executing on API Developer Experience KeshavVasudevan @keshinpoint 8th Nov 2017
- 2. Page Proprietary & Confidential IncreasedOpportunities With PSD2 PSD2isa dataandtechnology-drivendirectivethataimsto- IncreasecompetitionImproveinnovation Encouragetransparency Addrevenuestreams 2
- 3. Page Proprietary & Confidential Explosionin the API Economy 0.3 0.6 0.9 1.5 2.4 3.4 7.2 10.3 12.2 14.1 16.1 0 2 4 6 8 10 12 14 16 18 0 2006 07 08 09 10 11 12 13 14 15 16 9 Millon developersworking onprivateAPIs 85% ofenterpriseswill haveanAPIby2018 100,000 PublicAPIs 3
- 4. Page Proprietary & Confidential TheMulti Platform Ecosystem A platform is a product that canbe extended by users for the benefit of others Average consumer Third party developer 4
- 5. Page Proprietary & Confidential Examplesof Platforms 5
- 6. Page Proprietary & Confidential DevelopersAre Humans Too DX is the aggregateof allthe experiencesa developer has when interactingwith your Platform,usually through an API 6
- 7. Page Proprietary & Confidential WhyDeveloper Experience Matters? Growth and Adoption: The value of anAPIincreases when users reachcriticalmass PreventsSwitch: MakesAPIs differentiable and competitive Helps drive business and technological goals 7
- 8. Page Proprietary & Confidential WeDo Better With Products We Enjoy Using 8
- 9. How to ThinkAbout API Developer Experience
- 10. Page Proprietary & Confidential ADX Focus Focusses on solving an actualhuman need Focusses on driving the business Focusses on sustainability 10
- 11. Page Proprietary & Confidential 3Step 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 Step1: 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
- 13. Page Proprietary & Confidential Step2: Understand their Journey Why should I use it? How do I register? Where do I start? How do I use it? 13
- 14. Page Proprietary & Confidential Step3: 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
- 15. Optimizing Your API’s DeveloperExperience
- 16. Page Proprietary & Confidential BeforeWe 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
- 18.
- 19.
- 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
- 21. Page Proprietary & Confidential Example:CapitalOne DevExchange 21
- 22. Page Proprietary & Confidential Example:Open Bank project 22
- 23. Page Proprietary & Confidential Example:Dropbox; MailChimp 23
- 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
- 26. API Documentation andthe OpenAPI Specification
- 27. Page Proprietary & Confidential Whatis 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
- 28.
- 29. Page Proprietary & Confidential TraditionalAPI Development and Documentation Technical Writer Developer Tester Architect Request Response
- 30. Page Proprietary & Confidential MajorProblems 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 RESTfulInterface Call the API (request) Obtain data (response) Restful Interface Technical Writer Developer Tester Architect Keeps in Sync 31
- 32. Page Proprietary & Confidential TheOpenAPI 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
- 33. Page Proprietary & Confidential Exampleof an OAS Defined API Requests Responses API Overview 33
- 34. Page Proprietary & Confidential Exampleof Documentation Hosted on SwaggerHub 34
- 35. Page Proprietary & Confidential CreatingEffective Documentation
- 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 Tipsfor 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
- 38. Page Proprietary & Confidential Tip1: List the Fundamentals Authentication Errors End Points Terms of Use Changelog Examples 38
- 39. Page Proprietary & Confidential Authenticationin OAS • OAuth 2 –Implicit –Password –Access Code 39
- 40. Page Proprietary & Confidential EndPoints in OAS 40
- 41. Page Proprietary & Confidential HTTPCodes and Examples in OAS 41
- 42. Page Proprietary & Confidential Example:Changelog and Terms of Use Box Google 42
- 43. Page Proprietary & Confidential Tip2: 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
- 44.
- 45. Page Proprietary & Confidential Tip3: 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
- 46.
- 47. Page Proprietary & Confidential Tip4: Experimentation is Power Thedifferencebetweendocumentationandgooddocumentationisalittlemoreeffortwith theseNice-to-haves. Allow developers toexperiment withyour API 1. Getting StartedGuides 2. InteractiveDocs and Console 3. SDKs 4. Tutorials 47
- 48. Page Proprietary & Confidential Examples:Braintree 48
- 49. Page Proprietary & Confidential Examples:Microsoft Graph 49
- 50.
- 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
- 52.
Editor's Notes
- #5 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.
- #7 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
- #13 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/
- #14 Mention how designers and documentation writers should partner with marketing
- #15 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/
- #17 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.
- #33 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
- #34 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”
- #35 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.
- #44 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
- #46 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
- #48 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
- #50 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/