Downloaded 28 times
Uploaded bySmartBear
Understanding and Executing on API Developer Experience
The document discusses the importance of API developer experience (DX) and outlines a three-step process to optimize it: understand the API's audience, their journey, and map that journey to the audience. It emphasizes the need for effective documentation, which is key to API adoption and growth, and provides tips for creating user-friendly documentation. Furthermore, it highlights the value of using the OpenAPI Specification to standardize API design and improve communication across different technological platforms.
More Related Content
Similar to Understanding and Executing on API Developer Experience
Understanding and Executing on API Developer Experience
- 1. 1 Understanding and Executingon API Developer Experience
- 2.
- 3.
- 4. 4@keshinpoint Number of ConnectedDevices No. of devices/person In 20207 devices
- 5. 5@keshinpoint The Multi PlatformEcosystem A platform is a product that can be extended by users for the benefit of others Average consumer Third party developer
- 6. 6@keshinpoint Developers Are HumansToo DX is the aggregate of all the experiences a developer has when interacting with your Platform, usually through an API
- 7. 7@keshinpoint Why DX Matters Wedo better with products and platforms we enjoy using
- 8. 8@keshinpoint Why DX Matters PreventsSwitch: Makes APIs differentiable and competitive Growth and Adoption: The value of an API increases when users reach critical mass Helps drive business and technological goals
- 9. 9@keshinpoint Speaking of Businessand Technological Goals Public APIs Priority: High Adoption Private APIs Priority: Low Cost Partner APIs Priority: High Adoption, Low Cost
- 10. 10 How To ThinkAbout DX SmartBear Proprietary & Confidential
- 11. 11@keshinpoint Goals for DoodDX Solve a Consumer Need Help the Business Built for sustainability
- 12. 12@keshinpoint Three Step Processfor Good DX Step 1 Understand the API’s audience Step 2 Understand the audience journey Step 3 Map the audience to the journey
- 13. 13@keshinpoint Step 1: Understandthe 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
- 14. 14@keshinpoint Step 2: Understandtheir Journey Why should I use it? How do I register? Where do I start? How do I use it?
- 15. 15@keshinpoint Step 3: MapJourney 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
- 16. 16 Recommendations to OptimizeEach Phases
- 17. 17@keshinpoint Follow the 3:30:3Rule 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
- 18. 18@keshinpoint 3.a. “Why ShouldI 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
- 19. 19@keshinpoint Examples Twilio Know exactly whatthe value is, and what it’s mean to be used for
- 20. 20@keshinpoint Examples Dropbox Pleasant to read,easy to understand, with example use cases, all in the first section of the landing page
- 21. 21@keshinpoint 3.b. “How ShouldI Register?” How do I register? Focus: Decision Makers, API Users Explain setup in comprehensive fashion Recommendations Minimal steps to register – 30 seconds Provide API console
- 22. 22@keshinpoint Examples Make Sign upstraightforward Dropbox asks you for your name, email and password for the free API key. It also allows Google sign in. Straightforward process with Mailchimp as well.
- 23. 23@keshinpoint Bad Examples Jumping through hurdles- 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. 24@keshinpoint 3.c. “Where andHow Do I Use it?” Where do I start? How do I use it? Documentation Focus: API Users Focus: Decision Makers, API Users
- 25. 25 API Documentation andthe OpenAPI Specification
- 26. 26@keshinpoint What is APIDocumentation •Documentation is a deliverable of technical content, containing instructions on how to effectively use your API –> usage manual •Good documentation can be a determining factor is API adoption and growth An API is only as good as its documentation
- 27.
- 28. 28@keshinpoint Traditional API Developmentand Documentation Technical Writer Developer Tester Architect Request Response
- 29. 29@keshinpoint Major Problems Maintaining documentation,tests and implementation is hard Implementation comes at a cost of user experience Communication between services built in different programming languages is not easy
- 30. 30@keshinpoint RESTful Interface Call theAPI (request) Obtain data (response) Restful Interface Technical Writer Developer Tester Architect Keeps in Sync
- 31. 31@keshinpoint OpenAPI Specification isthe Answer Allow machines/tools to integrate with API Allow humans to implement API code Allow humans to read and generate API documentation and test cases
- 32. 32@keshinpoint The OpenAPI Specis the API Contract •The OAS is an API description format to Design and Document REST APIs •The OAS defines your API’s contract •Connects computers, technology stacks and humans in one unified language
- 33. 33@keshinpoint Evolution of theOAS •2010 – Wordnik created and open sourced Swagger Specification •2010 to 2015 – Massive adoption of the Swagger Specification, with Swagger tooling developed by community •2015 - Swagger Spec and core tooling acquired by SmartBear •2015 – Open API Initiative was create to standardize REST design. Swagger Spec was renamed as OAS
- 34. 34@keshinpoint Example of anOAS Defined API API Overview Request s Responses
- 35. 35@keshinpoint Example of Documentation Hostedon SwaggerHub
- 36.
- 37. 37@keshinpoint Effective Documentation Tips •Documentationplays a central role in the way APIs are perceived by a User •Tip 1: List the Fundamentals •Tip 2: Write for Humans •Tip 3: Explain your Request-Response Cycles •Tip 4: Empower with Experimentation
- 38. 38@keshinpoint Tip 1: Listthe Fundamentals Fundamental sections in every documentation Authentication Errors End Points Terms of Use ChangelogExamples
- 39. 39@keshinpoint Authentication in OAS •Basic Auth • OAuth 2 –Implicit –Password –Access Code
- 40.
- 41.
- 42. 42@keshinpoint Changelog and Termsof Use Box Google
- 43. 43@keshinpoint Tip 2: Writefor Humans Never Assume 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
- 44.
- 45. 45@keshinpoint Tip 3: Explainyour Request-Response Cycles •Your API Users should know exactly what to expect from a successful call •Describe full sample response body in every supported 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
- 46. 46@keshinpoint Examples Stripe All the ErrorCodes are described in a separate section for users to follow
- 47. 47@keshinpoint Examples YouTube Well detailed parameters,with an overview section of every resource. These resources are all organized in an easy to follow navigation pane
- 48. 48@keshinpoint Tip 4: Experimentationis Power The difference between documentation and good documentation is a little more effort with these Nice-to- haves. Allow developers to experiment with your API 1. Getting Started Guides 2. Interactive Docs and Console 3. SDKs 4. Tutorials
- 49.
- 50. 50@keshinpoint Examples API console Microsoft GraphExplore lets you try various end points and see what the response packet is
- 51. 51@keshinpoint Summary •Good API DeveloperExperience can help drive business and tech goals •Three step framework for understanding API DX –Understand audience –Understand journey –Map journey to audience • Tips for Good API Documentation –List the Fundamentals –Write for Humans –Explain your Request-Response Cycles –Empower with Experimentation
- 52.
Editor's Notes
- #3 APIs, in a nutshell, allow different products and services to talk to each other.
- #4 The API revolution can be seen in the number of public APIs that exist right now. It’s estimated that we have about 20,000 public APIs, not counting the partner APIs, or the millions that exist as private APIs. This number is from looking at the number of public APIs in the programmable web directory, as well as the predictions made by getElastic. This number is said to be lower than what is actually out there, and different sources report differently. APIhound for example, estimates there are 50,000 public web APIs.
- #5 This number is only set to increase with the exponential rise in the number of connected devices. The IOT revolution is upon us, with home devices, bots, VR and AR, all contributing to our growing desire to stay connected. By 2020, it is estimated that every person in the world will have, on average, 7 devices. The IoT market is predicted to grow to 1.7 trillion by 2020. This is further proof why organizations should start thinking about their API strategy, since APIs are the best way to penetrate across all these devices as a data rich channel.
- #6 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
- #9 Ronnie Mitra, a prominent spokesperson for developer experience, says that if an API has bad DX, and developers aren’t required to use it, you can bet they won’t.” And of course, the upside to having good developer experience, is that there’ll be an increase in adoption of your APIs, which would lead to innovative ways for your end developers to improve on your platform’s functionality. There will be more people talking about it, making your services credible and authentic, which would drive towards increased growth of your products and higher demand for your services. Usability does not triumph Utility
- #12 A good developer experience should strive for three goals Good DX will help solve a consumer need, or alleviate some of the pain points in their existing processes It helps the business – as I mentioned in the previous slides, good DX leads to better adoption, and more users adds more value to the services distributed via the API for the business Finally, an API that has a DX oriented focus can last longer, as more users will have dependencies associated with the API
- #13 There is a three step framework I would recommend applying to craft an optimal experience for users consuming an API. The first step is to understand the Api’s audience intimately – their personas, charecteristics, and what they’re trying to achieve or accomplish. From here, you have to learn their journey from API discovery to consumption, and the various steps between them Finally, you map the right audience to the different phases in their journey, and optimize the experience. Lets walk through this
- #14 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/
- #15 Mention how designers and documentation writers should partner with marketing
- #16 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/
- #18 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.
- #19 Let’s start with the first phase of the Developer Journey – the Why should I use it aspect. This aims to provide your audience a high level message abd overview of your services in a way that immedietly resonates with the tasks they want to accomplish. Focus on the homepage itself and what message it conveys to visitors. Developers should quickly understand the main feature your API is offering and how they can start using it. This is where the human interacts with the information presented before them for the first time. Since this is a product marketing exercise, the writer must jump into the psychology of the user, considering that upon visiting a site for the first time, a user needs to know what I can do with this API and why I should use this API. http://nordicapis.com/beautiful-ui-design-for-api-developer-portals/
- #22 Decision makers and Users, both want to try your API First step is to obtain an API key After the audience understands your value and what it would mean for their, their next step would be to register with your system in order to try and start using your API. The registration process should be as straightforward as possible, but you should be able to obtain all the information you need during this phase. A good strategy is to let developers sign up using a popular third-party service like Twitter and GitHub. You need to be able to quickly capture your user’s name and email address, without making them go through too many hurdles. http://nordicapis.com/5-reasons-why-developers-are-not-using-your-api/ Documentation should quickly take developers to a stage where they’re already using the API with little or no effort. One possible way to make this happen is to create a “sandbox environment,” where developers can play with the API without actually hitting your production servers. This allows you to offer a minimum signup process, asking only what is really needed instead of a lengthy registration process that can drive many developers away. Good documentation should clearly inform developers of what they must do to get started — and how to do it. If your API works with API tokens, generate one on-the-fly and let developers use it right away. If you use OAuth, provide fake consumer information, and even an access token, so developers can start making API calls immediately. Remember that this is only the first step of engagement, and developers are still evaluating your API. You should let them experiment as much as possible, but without compromising your production systems or any real user information. http://nordicapis.com/spark-api-adoption-good-documentation-practises/
- #25 So we finally come to the last stages of your developer journey. Your audience understood your services value proposition, it ignited their interest, and they went on to register. Now is the time they would want to get their hands dirty with your API, trying it out and eventually integrating it with their own apps. How do you guide them through this journey? Documentation. API documentation, also known as Programmers documentation, is a deliverable of technical writing with good instructions about how to effectively use it. If you get your documentation right, more people will find value in your services easily, leading to better growth and adoption. Remember, your API is only as good as your documentation As a good start, having clear and up to date documentation is a great way for your users to understand how to use your API. Users are going to spend a fair amount of time reading the documentation, therefore it should be considered part of the product. And of course, having great documentation has a direct correlation to adoption and growth .
- #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
- #35 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”
- #36 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.
- #37 So let’s dive into this phase a little more. Let’s understand API documentation better. Among all the API-related phases, documentation is probably the area showing the most growth. This is especially true with the tooling ecosystem around documentation. It’s interesting to note this trends, since documentation is traditionally something that developers pay little attention to when launching code.
- #38 API Documentation, as mentiponed before, is the technical writing to understand how to use your API, and is crucial to take the user to success in the last 2 stages of their journey – How do I get started, and use the API
- #39 These are the sections that every API documentation should offer. Without these sections consumers will have a very hard time understanding how your API can be used, and, in many cases, they could even stop using your services. Authentication information about authentication schemes your API uses. information, describing which authentication scheme your API uses. If you’re using OAuth, don’t forget to explain how to setup an OAuth application and obtain the API Key and Secret. Errors and how they’re communicated to API consumers. Exlain the error standards, and also provide solutions on how to overcome them. Endpoints and information on how to consume them, including requests and responses. This is considered the main section where you expose all your API methods, explain how they can be reached, and note what kind of parameters are allowed. Examples of how to consume your API, including starting from scratch but also displaying use cases where your API would come in handy. Include plenty of code and, if possible, case studies with actual API consumers and example applications. Terms of Use, including API Limits and other best practice terms and conditions. Constraints need to be clearly stated so that consumers understand what API usage and practices are permitted A Changelog detailing latest updates and how they might affect API consumers. This will help consumers know the stability of the API and see if any changes made to the API calls might impact their application. With these sections you’re off to a great start because you’ve already documented most of what is needed to consume your API and your offering. But, as you’re about to find out, this is often not enough. As you obtain more sophisticated consumers, you’ll end up having to offer them documentation on non-functional aspects of your API. http://nordicapis.com/using-templates-for-documentation-driven-api-design/
- #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
- #49 A little more effort goes a long way in actually enabling developers to actually reach success with your API in their software programs. There are some good nice to haves, listed here. The key takeaway is to have a great way for your consumers to get on-boarded and use your API. Start with a getting started guide. It’s a great start from API newcomers, and helps them quickly understand what your API can do. Remember the 3 minute rule, so try to create a getting started guide that helps them obtain an end result in 3 minutes or less. Interactivity in your API documentation is a great way to let developers test your API, without actually integrating it in their application. The sandbox or console should be easy to deploy and reset whenever needed. The more SDKs, the better. SDKs aren’t always the best go-to market strategy, but once your API is out, it’s a great idea to invest in building client libraries that allow devs to effectively use your API. If a lot of developers are finding value in your services easily and effectively, they might even build SDKs for you. It’s all about dev relations, and focusing on their experience using good documentation is a step towards achieving this. Publish tutorials: Provide sample snippets using the SDKs in as many languages as possible, with example use cases and tutorials to achieving different results
- #51 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/