DEV Community: Hoss

Developer Enablement Unpacked: Developer Experience, Relations, and Marketing

Matt Hawkins — Fri, 14 May 2021 22:20:16 +0000

Public APIs create value—for the provider and the consumer—only when they’re used. That’s why fields that attract and support developers have grown in recent years. These individuals and teams enable developers to discover and better use APIs and other technical tools. Once a part of only the largest companies, these roles are now more common at medium-sized businesses and even startups.

We’ll cover three common areas companies use to interact with a developer audience:

Developer Experience
Developer Relations
Developer Marketing

You may find these by other names, but they’re the core pieces of developer enablement—and they’re crucial to both attracting and retaining developers.

Developer Experience: How You Guide the Developer Journey

Once a developer has discovered your API, they may want to use it. Your developer onboarding will determine whether they can quickly get started. These earliest interactions determine their initial developer experience. How you further guide them will determine whether they stick around to be successful with your API.

There are many factors that go into this hands-off developer enablement. There are product decisions, user interface elements, and technical education that all need to come together. If you’re clear about why and how to use your API, you’ll enable developers to accomplish their goals.

A robust developer experience will quickly answer what is possible and help them take the next step. The most valuable tools of the developer trade are all varying forms of documentation. Yes, there are various types of documentation you need to provide a developer to enable them to succeed. Make sure you have at least all of the following, if applicable:

A getting started guide;
Tutorials;
An up-to-date reference guide;
Sample applications

For example, Deepgram meets developer needs in its documentation portal:

For someone brand new to Deepgram, it provides a guide to get started. The complete reference is useful for a quick glance at what’s possible or an experienced developer checking on syntax. Finally, guides and samples bridge the gap between first interactions and complete integrations.

Of course, the specifics of your documentation will vary based on your API. This is a great chance to use your product knowledge to customize the documentation with the context needed to truly empower your users. Just make sure you avoid these 10 common developer experience mistakes.

As great as your self serve experience should be, remember developers are people, too. Sometimes direct interaction and the support of others unlocks their full potential. Let's look at how developer relations can amplify your developer enablement.

Developer Relations: Coders Helping Coders

Communication is a crucial element of your developer onboarding, but it doesn’t all have to be in your developer experience. Self-serve signup is great, but so is a friendly face to point out the time-wasting gotchas. No documentation can cover all of those, nor have the same empathy as another person. The field of developer relations can fill these gaps.

Some of the common titles you’ll see in developer relations include:

Developer advocate
Developer evangelist
Community manager

The exact responsibilities may vary, based on title and organization, but the overall duties are to enable fellow coders to be successful. Google first popularized the “advocate” title, which it meant to include bringing product feedback from the outside into the company (being an internal advocate for external developers). By contrast, “evangelists” face outward and spread the good word of the company. In practice, some advocates may be promotional and some evangelists bring tremendous insights back to their employers.

While the example of a new developer onboarding can look like customer support, that’s only one type of communication. Developer relations practitioners attend events, host live coding sessions, and jump into open source forums, among many others.

Even after integrating with your product, developers run into issues the documentation may not answer. It might be specific to their situation or industry. In traditional developer fashion, they could just go down a rabbit hole of hit-or-miss StackOverflow threads. But often an advocate, evangelist, or community manager can provide a quick, helpful point in the right direction.

Once you develop those relationships, it's important to take steps to maintain them throughout their time using your product. A great way to be helpful to developers and to support those relationships is through having a presence in the communities where they congregate. These communities can be of your creation, such as product-specific forums, or be of pre-existing platforms, such as Twitter and Reddit. Just look at all the ways developers can interact with each other from Twilio's website:

Making use of one of these should not be mutually exclusive from using the other; each has its own advantages. By having a presence on pre-existing platforms, you'll reach developers who might not have realized your product is the solution to their problems otherwise. And by having your own product-focused community, you create an informative, communicative dynamic between people using your product.

We believe that communicating with developers is important, as you can see, but that assumes you’ve helped them discover you in the first place. Let's look at what you can do to address that concern.

Developer Marketing: Go Find Your Technical Audience

Before a developer can enjoy their first experience or ask a question of your advocate, they need to find out you exist. As with other fields, marketing can help you find an audience. Unlike other fields, developers are especially uncertain about most marketing activities, so you’ll need to be careful how you reach out.

Luckily, most developers are always looking to learn and expand their abilities. If you can help them on their journey—before they’ve even used your product—then they’re more likely to trust what might otherwise come across as promotional messages.

Some common and successful developer marketing tactics are:

Events and webinars
Content marketing
Community sponsorship

You can use any of these approaches to show up where developers already participate.

Bring information to developers when you participate and host events. Help them find the next new thing, or understand better how the current things work. Keep your product promotion low key or non-existent and instead focus on how you can communicate about the problems to developers before working on the solutions.

You can do the same in SEO-focused content marketing and advertising-focused community sponsorships. Show yourself to be a key resource and developers will be willing to hear from you. Use other tactics like retargeting and email newsletter to stay top of mind.

For example, cloud database Snowflake puts it all together in this email:

It’s an event related to specific problems that Snowflake solves. A Q&A session offers the chance to ask questions of experts (perhaps their developer relations team?). All of these resources could then be bundled into content to attract more developers to their platform in the future.

Naturally, you’ll want to include all of these resources within a framework that provides the best experience and access to your own team of experts. How you treat developer enablement in your organization will greatly determine the success of your API. Consider the Hoss developer hub to host not just your documentation, but the full enablement experience.

Reach out to us to learn more about what we’ve built.

How to Prevent API Limits From Breaking Your Stack

Matt Hawkins — Fri, 27 Nov 2020 22:15:57 +0000

Imagine your favorite take-out restaurant on a busy night. There’s a line out the door just to pick up the food that’s already been ordered. If you could walk right up to the register, you’d only get your food if it’s ready. There’s a natural delay built into delivering the orders. And there’s a maximum amount of dishes that can be cooked during a time period, set by the kitchen equipment and staff. In API terms, this restaurant has rate limits. They’re good for both parties, both in restaurant and API terms.

However, for a developer consuming APIs, rate limits are difficult to handle. Immediate results—success or error—fit much better into their development practices. When you reach a rate limit, or quota limit, you’ll need to stop your API calls based on the response from the server. In this post, we’ll further describe the purpose of API limits, how they cause problems for developers, and how you can prevent the failures that can come from them.

Quota and Rate Limits: Definition and Purpose

If quota and rate limits in APIs are such a pain for developers, why do they exist? The answer is for the provider. But like the restaurant and customer, the eventual benefit is mutual. Just as the quality of the food would decrease with too many orders, an API’s reliability is dependent upon rate limiting its requests.

While quota limits and rate limits are often used interchangeably, they also imply slightly different meanings:

Quota limits usually refer to an allotted number of calls over a longer period of time and could be determined by your account level.
Rate limits typically cover a short period of time—such as a second, minute, or hour—and ensure every API consumer can have successful requests.

It’s understandable why these are important for providers. When too many users attempt to access an API simultaneously, it can put too much strain on the servers. This threatens to slow the service down or crash it completely.

If an integration tries to call an API more frequently than the given rate limit, the request delivers a limit exceeded error code of 403 or 429 along with a short message:

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 60

In this case, the response suggests the integration can try the call again in 60 seconds. Pretty simple for a human to understand, but a bit different to architect a system that can handle that kind of delay. For many developers, quota and rate limits turn into temporarily broken integrations.

Why API Limits Break Stacks

Modern software includes a stack of tools where you do not have complete control. For example, you likely deploy to the cloud, rather than physical servers you can see and touch. You trade that control for the advantage of scale and redundancy. Similarly, developers build on third party APIs to achieve features they would otherwise not have available. You may even connect to external tools your customers use, which would not be possible without an API. Like relying on the cloud, APIs bring advantages, even if you don’t control every aspect.

The lack of control means that errors, downtime, and unexpected responses can come at any time. Your software needs to build in resilience, but sadly many integrations fail silently. The result is your customers know your app broke, but you have no visibility into the issue.

API limits are another type of this unforeseen error. As we’ve mentioned earlier, it’s also a more difficult type of error because it’s impermanent. The same API call, repeated later, will succeed. Instead, many developers treat rate limits the same as incidental errors. They may keep retrying, which will continue to have the same result, because you’ll still be above your rate limit. Alternatively, they stop trying completely, and display a generic error to the end user.

One reason API limits aren’t considered during development is they’re out of sight. Many APIs share rate limits in documentation, but far more don’t even mention them. Regardless of whether a developer knows about the limits, they still may not account for them. During development, it’s unlikely to hit rate limits, which means it’s an error the developer may not see.

A stack will frequently include multiple third-party APIs. When you add rate limiting to the many ways an external service could break, you’ll find it can take down your entire stack.

How to Prevent API Limit Failures

The first step is to acknowledge that API limits are a problem. If you aren’t looking for them, you’ll never be able to create the resilience to handle them. The good news is the effort you make with quota and rate limits can be used for other types of errors, as well. As you architect your integrations, you want to include cases of success, permanent failure, and temporary failure. It’s the impermanent errors that can turn into successful calls.

Where your API call starts will determine one way that you handle it. For example, if you are tracking HTTP requests in the browser, you may need to provide a message to the end user before retrying. On the server-side, you may be able to handle retries without interrupting the user experience.

Among the errors you can solve with an API call retry architecture:

Rate limiting with retry response
Quota limit based on daily allotment
Authentication error that requires a refresh token
Some 500-level status codes

To implement this yourself requires updates in all your code that makes API calls, as well as a system to queue and re-initiate API calls.

Alternatively, you can use a tool like Hoss to handle the hard parts for you. With Hoss, you can prevent API limit issues that affect your customers by applying reliability features, such as auto-retry and failover, uniformly across all of your integrations. You can increase the robustness and perceived reliability of your applications, with minimal updates to your code.

It’s not enough just to know errors occurred. Approaches like synthetic testing and monitoring is not enough. You want to have visibility into errors, but also increase the resilience of your third-party integrations. Try Hoss for free and see how it can help save your stack from API limits.

The Hoss 2020 Developer Experience Report

Matt Hawkins — Tue, 17 Nov 2020 22:59:50 +0000

At Hoss, we’re obsessive about developer experience. Developers’ needs and preferences are constantly evolving, so our 2020 Developer Experience Report is a pulse check about what developers expect from API companies right now, and which companies are meeting those expectations. Here’s what the results have to say about experience in 2020:

Great developer experience is industry agnostic.

While 20% of those surveyed reported working in the financial services industry, developers were otherwise remarkably evenly split across the full spectrum of industries, from media and retail to consumer goods and healthcare and life sciences. Every industry is clearly becoming increasingly API-driven (a recent report predicted this would be the case in 2020 and beyond), meaning that no industry is immune to the importance of providing a great developer experience.

The recent Bessemer Ventures State of the Cloud Report 2020 predicted that the API-Universe will drive innovation across all industries and that “there are massive API companies worth billions of dollars in every industry that will further drive digital transformation.”. We certainly agree that the API-Universe is expanding rapidly.

There is significant room for improvement in developer experience today.

On average developers rated the developer experience of APIs they regularly work with 5.7 out of 10. Clearly, there is room for improvement. As the API industry becomes more competitive every day, it will be increasingly important to provide a great developer experience.

Great documentation is more important than you think.

92% of developers list clear and concise documentation as a must-have in any API developer portal. While developer experience can’t be limited to just one great service, this overwhelming response illustrates that great documentation is mandatory. One-third of developers surveyed said that this critical must-have is often missing from the API developer portals they use.

Developers want better tutorials and guides.

After documentation, developers reported helpful tutorials and SDKs or code samples as must-have runners up. While 62% said they consider tutorials and guide a must-have, 46% also said that helpful tutorials and guides are frequently missing from API developer portals, representing an opportunity for companies who want to improve overall experience.

Developers want to be self-reliant. Help them help themselves.

85% of developers say they prefer to research and solve the problem on their own. That could include the use of API documentation, guides and FAQs or third-party resources like StackOverFlow. Meanwhile, only 5% say they prefer contacting support for help solving a problem. It’s important for API companies to acknowledge this strong preference and make it as easy and frictionless as possible for developers to solve problems on their own by providing readily available, intuitive tools, as well as contribute to third-party communities to ensure content is up to date.

Sometimes developers do need support.

While developers prefer to solve their own problems without contacting an API’s support team, 56% said they need to contact support at least monthly. But 26% of developers said that API companies frequently don’t have an easy way to contact support. When the need arises, 36% said they prefer to engage with a support team via email, followed by 26% who prefer to use a messaging service like Slack or Discord.

Developers like community.

Most developers actively participate in and value online communities – 77% said they participate on StackOverFlow, 61% on Github, 56% on Hacker News and 44% on Reddit Programming. API companies who want to provide a great developer experience should participate in these communities, contribute helpful content, answer questions, and learn from users. Communities are an excellent source of product feature and content ideas.

Stripe is considered the gold-standard.

If you’re looking for an example of great developer experience in 2020, look at Stripe. Developers preferred the Stripe experience by a landslide, followed by a three-way tie between Github, Google and Twilio.

What makes Stripe so great? They are known for their high quality, interactive documentation, they offer helpful tutorials and guides, provide code samples, have a clear and simple way to contact support when needed, and offer a number of other great features like an API changelog, API status updates and more – all of which are easy to find at a glance and intuitive to use. Creating and maintaining all of these resources takes a lot of time and money, but clearly Stripe’s attention to experience is resonating with developers.

Interested in developer experience? Download our free ebook about the New Era of Developer Experience.

10 Ways to Create Delightful Developer Documentation

Matt Hawkins — Sun, 15 Nov 2020 19:10:02 +0000

Good documentation is critical to an API’s success. Without it, implementation is slow, problems are hard to solve, and developers are frustrated. Every API provider should prioritize excellent documentation as a central piece of its developer experience strategy.

Why is everyone’s documentation so bad?

Developers find most API documentation tedious and unhelpful. In fact, according to our Hoss 2020 API Consumption Trends Report, poor documentation is the number one API complaint cited by developers.

Bad documentation often doesn’t include a guide to quickly getting started, is out of date, inaccurate, incomplete, inconsistent, and/or has poor navigation and a confusing user interface.

So, why is this happening? What are the all-too-common documentation pitfalls that API providers keep falling into?

Not making documentation a priority.Teams that aren’t given the time and resources to write great documentation or who focus solely on writing code won’t be able to compete in the increasingly crowded API space.
Not keeping documentation up to date. Documentation can become dated quickly. Too many teams either don’t update their documentation or update it manually (instead of automatically) after new releases.
Making assumptions about the audience. Never assume that developers are familiar with specific jargon – or even that your audience is 100% developers.
Overtaxing developers. Developing and writing are two very different skill sets. It’s a lot to ask of a developer to build a tool and to write about it in detail. Even if you have the skills, writing documentation is a lot of work – a lot of developers simply don’t want to do it.

The 10 ways to create delightful developer docs

Now you know what not to do when creating documentation for your API – but how can you delight developers who use your products?

1. Be comprehensive.

Developers reference your documentation and your website for a wide range of reasons - so don’t scatter the answers in different places. Your documentation should represent a convenient, one-stop shop for developers, whether they’re looking for tutorials, FAQs, helpful blog posts or links to external resources like YouTube videos and developer forums.

2. Start with the basics.

Believe it or not, very basic answers to questions like “what does this API do?” or “how can I start integrating this API?” are very often left unanswered in a company’s documentation.

Start at the very beginning – authentication details to start using your API, information about error standards, endpoints (how to consume them, how request and response works) – the basics. A huge and basic help to developers is to provide a changelog in your documentation that lists all of the recent updates to and versions of your API and how they might impact usage of your product.

3. Be clear and concise.

Don’t use jargon or be unnecessarily wordy. Keep documentation simple, clear and easy to read. Most developers’ goal is to understand an API or solve a problem as quickly as possible, so parsing through unnecessary prose is counterproductive. Remember that developers are human, too – and humans don’t like to read things that don’t make sense.

4. Be consistent and stay up to date.

Keep language in your documentation consistent and ensure that anyone who contributes to it or publishes an update adheres to a standard style. For example, decide whether you’re going to use the term “function” or “method” to describe a certain action – don’t switch between the two. Consistency can get lost as updates are made to documentation by different authors at different times, so it’s important to set this standard from the beginning to avoid confusion.

Which brings us to keeping documentation up to date. Staying current and correct is critical, as out of date and incorrect documentation is essentially useless to developers. But this requires a fair amount of maintenance. Make sure you have a plan in place for updating documentation after any new releases, updates or issues, and consider implementing automatic updates.

5. Provide a getting started guide.

This simple addition to your documentation is highly valued by developers and significantly reduces friction around using your product. Hoss’s favorite examples include Plaid and Vonage.

6. Include language-specific code snippets.

Writing code snippets for your users and including them in your documentation will save many, many hours of their time.

7. Make your documentation interactive.

Interactive documentation provides a space for developers to test their own examples before implementing them. One of Hoss’s favorite examples is the Dropbox API Explorer.

8. Provide tutorials.

Make it easy for developers to understand the possibilities of your API by providing simple tutorials for specific use cases. Vonage has a great use case tutorials section in its documentation.

9. Have a comments section.

Developers respond well to community and appreciate the opportunity to share and discuss problems, workarounds and questions. This can also take the form of a dedicated online community for your users, where you can surface frequently asked questions to make it simple for developers to find what they need quickly.

10. Prioritize good navigation and UI.

Make information easy to find and navigation intuitive. A prominent search function is a key component of great UI in API documentation as it makes finding the specific question a given developer might have infinitely faster.

“Sticky navigation,” where the navigation bar remains visible as the user scrolls, is another good practice for navigating documentation, because the pages can be quite long. Auth0 and Algolia are great examples of this practice. Another helpful tip is to incorporate a “saved scroll state,” which keeps a user’s place if a user refreshes the page. It also allows the user to share their specific place in a document by simply sharing the URL of the page.

Don’t disappoint, delight.

Creating great documentation can be a lot of work, but it’s important, and the payoff for your users is huge. If you make documentation a priority and follow the 10 steps above, you’ll be perfectly positioned to delight your customers.

Interested in reading more about developer experience?

Download the latest Hoss ebook: The New Era of Developer Experience: Delivering World-Class Support in a Competitive Landscape.

Track JavaScript HTTP Requests in the Browser

Matt Hawkins — Tue, 08 Sep 2020 16:22:00 +0000

As a developer, you want your web application to work. That may be an obvious statement, but it leads to an important question: How exactly do you go about ensuring that? For many developers, the following scenario may seem familiar.

You create your application and test it locally. Great! It works locally. You then make sure it runs in production. Because you’re thorough, you make sure it works in multiple browsers. After that process, you’ve done all you can. That must mean it works, right?

That’s what you think until users begin reporting errors. You’re then forced into the tedious position of trying to reproduce those errors. Since your app uses third party APIs, you’ll be lucky if you can actually do so.

If this situation is all too familiar to you, you should be interested in API monitoring. Unfortunately, the most common way of monitoring, server-side monitoring, comes with caveats. With server-side monitoring, you’ll only be getting insight for APIs calls made from the server, not the client. What you truly want is to see what’s happening on their machine.

Luckily, with client-side monitoring, you can get the client-side perspective you could only get from seeing their developer console. It’ll give you the reach of server-side monitoring while showing you exactly what your users are seeing on their end.

In this post, we’ll be showing exactly how client-side monitoring can help you monitor your user’s experience while using your application.

Developer Tools Only Shows Your Computer

If you were on the user’s machine, you’d have access to useful developer tools. Unfortunately, the only developer tools you can usually access are the ones tied to your local machine and session.

This does have its use, though. You could open it up and do some basic manual troubleshooting, for example. With Chromium’s developer console, you can see exactly what’s going on as you access a website. Specifically, you can make use of the network tab. There, you can see all the JavaScript requests that happen after the website was loaded. This is where you can see any outgoing API requests.

For example, we can use the home page of the Star Wars API to make some sample requests to that API. As we do so, we can see the request information in this tab.

You get an accurate perspective of what’s going on from the client’s point of view. Unfortunately, as you’re the client in this scenario, it won’t be particularly enlightening for monitoring your application’s actual usage. After all, you can’t see a customer’s developer console. For that reason, most monitoring is done on the server’s side.

Server-side Monitoring is Powerful

When someone monitors their API, they typically do so from a server. Server-side monitoring gives you the ability to monitor your app in a controlled environment. You control where the call originates, and you’re in control of the server the calls are coming from. From simple unit-testing to full integration testing, you can use server-side monitoring to ensure your application is running smoothly with sample calls.

This process of synthetic monitoring can give you more insights into what potential calls your users could be making. However, it's more accurate to be monitoring live calls. By doing so, you’ll get insights into how your API is handling requests. That’s one of the reasons why synthetic monitoring is not enough

That said, you’ll only be getting live updates from your server’s perspective. For this reason, there are some additional advantages to using client-side monitoring.

Client-side Monitoring is Possible

Server-side monitoring lets you test a vast array of calls, catching errors in the process. Wouldn’t it be great if server-side monitoring also gave you access to that wealth of information provided in a user’s developer tools? Well, if you want that type of monitoring, you’ll want to utilize client-side monitoring.

With client-side monitoring, you get visibility into every call that happens from your app’s frontend. You can monitor the errors users are getting, and have all the information available to try troubleshooting the issue.

It’s never good when a user informs you that your website isn’t working for them. WIth client-side monitoring, you’ll be able to stay on top of those errors as they arise. Whether there’s an error with your own API or its integration with third-party services, you can address the issue instead of letting it fester, frustrating users on your website without your knowledge.

Client-side monitoring can be achieved by using the Hoss JavaScript agent. Just by inserting this into your frontend code, you are now capable of monitoring all the HTTP requests your application is making for your users. For more information on this, and other ways to monitor your API, be sure to check out the rest of Hoss’s offerings.

Why Synthetic Monitoring and Testing is Not Enough

Matt Hawkins — Wed, 01 Jul 2020 20:36:57 +0000

Application development is increasingly dependent upon APIs, often integrating with many different services. To address uncertainty in these dependencies, many developers use synthetic tests to monitor their API activity. This common tooling helps you discover when an API is up or down, and whether it’s returning the expected results. While useful, synthetic testing cannot mimic the reality of today’s applications.

When your application uses multiple services, your tests will miss:

Internal microservices that don’t have public endpoints
Errors specific to real usage that you haven’t foreseen
Changes to your application after the tests are written

In this post, we’ll share more about these three scenarios, and explain why real-time monitoring of live API calls is the best solution.

Your Microservices Might Be Untestable

Traditional synthetic testing isn’t even an option for many enterprises today. If you’re building internal APIs that are not Internet-accessible, such as popular microservices architectures, you’ll be restricted to only public interfaces. Sometimes that is enough, but for sufficiently advanced use cases, it typically means you’re leaving much of your software untested.

Most synthetic monitoring tools run as SaaS. You log in to a dashboard and set up your series of API calls and criteria. Then, at defined intervals, the monitor calls the endpoints—typically from cloud providers in various locations—to ensure the synthetic tests pass. To achieve this test with microservices requires that the calls can be made from within your systems, which may not be accessible by public DNS.

You may be able to use synthetic monitoring with simpler scenarios:

An internal API running a mobile app or other frontend
Calling a small number of third-party APIs

In both of these cases, the endpoints must be accessible to the Internet. With some manual effort, you could create tests to periodically mimic these client-side calls. With this approach, you can only monitor pre-determined request and response data to ensure it matches expectations. Not only does this testing miss issues with internal services, it also only gives you a partial view of your external calls.

Synthetic Monitoring Only Tells Part of the Story

The problem with synthetic monitoring is in the name: it’s synthetic. You are only testing what you’ve explicitly included. Many errors are dependent upon real usage situations—if you haven’t accounted for it, your monitoring will not catch it.

Synthetic tests can miss:

Problems related to your application’s network
Edge cases based on the credentials you use
Bugs that only arise with dynamic request content
Latency not captured in a one-off test
Error messages sent with 200-level status codes
Issues you have not considered with your tests

These issues only become worse if your application depends on multiple third party APIs. We found over half of developers consume more than five APIs. With the many potential points of failure, you can see why it’s tempting to set up monitors. Yet, we discovered most developers don’t monitor the external APIs they call and may not have access to a sandbox that can be easily tested.

To understand the full picture into API performance requires total visibility to what your application is experiencing. There are situations where synthetic tests make sense, but you cannot depend on them to capture all the issues with your application.

If it’s important for your customers to have an experience with limited errors, it’s critical that you go beyond synthetic tests.

It’s Hard to Maintain Synthetic Tests

Where synthetic monitoring makes sense is for APIs that you provide publicly or for approved partners. The surface area of tests is limited to a single API with some well-defined use cases. Third-party API monitoring is more difficult, especially if you try to cover some of the scenarios synthetic tests can miss. External APIs often change without notice, so tests can give you alerts when things aren’t as you expect. Then comes the hardest part: maintenance of those tests when your own app is also changing.

Let’s say you’ve gathered the details of every API call you make during a typical user’s experience with your application. Next, you translate those use cases into synthetic tests, so you can be alerted when it catches errors. You’ll be missing atypical user paths, but that may be a trade-off you want to make. You can publish your tests and monitor them regularly, feeling somewhat confident. As long as you don’t change anything.

Once you’ve built an application, it’s not done. Most software requires bug fixes, user experience enhancements, and new features. Inevitably, you’ll need to adapt how you make your calls to external APIs. Building comprehensive synthetic tests for an application that calls multiple APIs is difficult in the first place. Keeping it updated with the exact calls as your code evolves might be an impossible task.

Ideally, you could add some process to sync monitors with your real calls. For example, include synthetic test maintenance in your code review. An unfortunate side effect could be slower development cycles. All in the name of tests that can’t even capture every scenario.

Use Real Monitoring for Real Visibility

We’ve bumped into all these issues, in our development work and with Hoss customers. Whether consuming your own microservices or third party APIs, our goal is to give you deep visibility and better customer experiences. Keep track of performance based on real scenarios, not synthetic tests. You can enable error alerts and reduce the amount of time spent debugging your integrations.

Try Hoss for free and save yourself the headache of synthetic monitoring.

3 Common API Integration Mistakes and How to Avoid Them

Matt Hawkins — Tue, 23 Jun 2020 20:55:18 +0000

If you’re building an app or have already deployed one, you probably used a good number of third-party APIs. After all, why build it yourself when you can plug in an API with the functionality you need? However, it’s natural to make certain mistakes when integrating APIs, and these mistakes can negatively impact app performance and user experience. This post highlights some common mistakes developers make when integrating APIs with apps and how to avoid them.

1. Don't Overlook Legalities Concerning API Use and User Data

When it comes to the terms of use, many developers make the mistake of only reviewing the policy at the time of integration. API providers sometimes change the terms of use for their APIs, and they don’t always notify users. If you’re using an API and are not following its current terms of use, the provider could ban you from using the API or you could face legal consequences.

It’s also important to consider the legalities of the data your app will store. Quite a few countries have regulations regarding user data, and your app must follow all applicable data privacy laws. Otherwise, you could face expensive fines and stiff penalties.

2. Don't Assume Third-Party APIs Will Always Respond as Expected

Some developers may not take the time to test and monitor third-party APIs for errors. Developers may also fail to add code that enables an app to work properly, even when an API doesn’t respond or returns an error. APIs become non-responsive or return errors for many reasons, including:

Downtime – Many API providers commit to an API uptime of 99-99.99%. But the reality is that every API will eventually experience a shutdown, whether it’s planned or unplanned.
Connection Timeout – Many providers program their APIs with default timeout values that are too short.
Rate Limits – API call volumes tend to be low during app development, but once the app is deployed, the call volume may hit the rate limit.
Bad Request – There are many reasons an API might return a “400 Bad Request Error.” It usually takes a lot of digging to figure out the root cause.

Don't make the mistake of assuming the APIs you’re using work perfectly. They might have hidden issues and you want to find errors before your customers do.

3. Keep an Eye Out for API Changes

It is a mistake to assume the providers of the APIs you’re using will always alert you of changes. While most providers alert users to changes with their APIs, some don’t. And the only indication an API change may be buried deep within the documentation.

Sometimes providers will change the design of an API or deprecate an API. They might change how methods are called or remove API functionality. They might release a new version of an API, which usually means new endpoint URLs. These API changes can break integrations and even bring down your app.

How Can You Avoid These API Integration Mistakes?

With the right tools and coding techniques, you can avoid the above API integration mistakes. Here are a few examples:

Review the Terms of Use and Research Data Privacy Laws

If you’re developing an app, you need to pay close attention to the terms of service for each third-party API you use. You must also make sure your app and any APIs you use comply with applicable data privacy laws. For example, if any users live in Europe, then your app must comply with GDPR. Do you have any users residing in California? Then you need to comply with CCPA. You need to do your research and code your app to comply with every applicable data privacy law. You should also use tools that enable you to track and control personal user data.

Code Your App to Handle Non-Responsive APIs and Errors

You can program your app to handle non-responsive APIs in any number of ways. For example, you could add code for asynchronous scripting, caching and automatic retries.

Asynchronous Scripting - App users shouldn’t have to wait for all the external scripts and APIs to load before they can view the main content. Asynchronous scripting allows the content of an app or a web page to load without having to wait for external resources. So, if an API is non-responsive, the content will load regardless. Many scripting languages feature asynchronous functionality, including JavaScript.
Cache API Responses - Caching API responses allows third-party API data to be stored on your server or in the client itself. The client retrieves data from a cache file instead of from the API server directly. Caching works best for API data that doesn’t change frequently. You can use caching to improve performance and potentially avoid outages or rate limits.
Automatic Retries - You should add code to your app that enables automatic retries. If an API is non-responsive or comes back with an error, the code automatically sends another API request. Most failed API calls can be retried immediately with successful results.

You should also code your app to handle the HTTP status codes for each API you use. Some providers publish detailed tutorials about how to do this.

Monitor Third-Party APIs for Changes

It’s crucial that you monitor every API for changes in availability, performance, speed and data format. Since most providers update the API documentation and changelog before sending out an update to users, you could periodically check these items for every API you use. A better option is to use API management software, as it monitors third-party APIs and alerts you to changes automatically.

Choose the Right Tools and Techniques

Choose your development tools and coding techniques wisely and you can avoid making these common API integration mistakes.

Hoss provides free visibility into the APIs you consume. Keep track of performance, get error alerts and reduce the amount of time spent debugging integrations.

How to Prevent Your Integrations From Failing Silently

Matt Hawkins — Wed, 10 Jun 2020 22:39:37 +0000

You open up a technical support ticket to some terrible news: a crucial part of your application is broken. After a little research, you discover an external API is returning different data than you expected. With a classic facepalm, you realize the worst part: you have no idea how long this has been happening.

If you’re learning about issues from your customers, you’re learning about them too late. Even when the problem is not your fault, you get the blame if you don’t have methods to detect these errors. In this post, we’ll look at what happens when APIs fail, some common causes of failure, and then some ways you can prevent failure—or at least catch it before your customers do.

What Happens When APIs Fail?

API integration is an expected part of modern development. Any project is likely to incorporate multiple APIs. Often, these tools help you save time and money. More importantly, they save you from having to “reinvent the wheel” and allow you to build the functionality of someone else’s tool into your own services. However, each time you add a new third party service to your stack, you take on additional risk.

When API integrations fail, they can make your whole app look broken. There’s a reason the support tickets come to you and not to the API provider. A huge value of API integrations - that they invisibly provide additional functionality - is also a major downside in the face of API failure. It means that from the customer perspective, you are the problem.

Good developers can build around this failure, up to a point. You can look for error codes. You can log problems to investigate. You can send friendly error messages to users (which - again - just make your app look broken from the user perspective). But error handling can only cover the ways you’ve anticipated that an API can fail. The silent failures - the ones you’re not watching for - are the ones that will leave you with no visibility into what went wrong.

Common Reasons Integrations Fail

There’s no universal fix for API failure. Your user may have discovered an edge case. Or an API you rely upon may have permanently made a change you need to build around. With typical logging tools, it can be difficult to distinguish between those two ends of the error spectrum. That said, there are some common things to look for when diagnosing API issues.

Common reasons why integrations fail include:

API deprecation
Connection timeouts
Schema changes
Authentication issues
Rate limiting
Provider downtime

Some of these are unavoidable. They’re part of the cost of building software that relies on internet connections. Many could be helped with better communication from API providers, but you can’t count on a heads up every time there is a change.

For example, it’s common for API providers to set rate limits. Their systems need to be able to scale, providing consistent service to all API consumers. It’s also common for API providers to not enforce their rate limits. What happens when that API usage increases? The first thing that API provider’s team does is enable rate limiting. Now your integration, which may never have been tested with these limits, must adapt.

In another example, you might have accidentally integrated against outdated documentation. Your initial tests could pass, but there could be common use cases that behave differently. Now your application might return authentication errors on certain endpoints because scopes have changed. Or, perhaps a common object now returns data in a different schema. These problems can crop up in even the most well-behaved APIs.

Then there are the times when it is the API provider’s fault. Sudden deprecations happen. Unpublished schema changes, uncommunicated downtime and unreliable latency are all real possibilities. They’re spread across all your APIs and you hope to catch them before they become issues in your application.

How to Prevent Silent Failure

Hope is not lost in the perpetual struggle against entropy and error messages. There are measures all development teams can take to minimize these failures before they become larger problems. What you need is more visibility into your requests, so you can see what’s working and what’s not.

API monitoring is a common way to keep an eye on metrics like latency, error rates and schema confirmation. Typically, these tools are built with providers in mind who are testing a single point of failure - their own API. But if you’re an API consumer, the problem is compounded with every API you integrate. While you could declare monitors across your stack, they would be running with predetermined data. In addition, they might become outdated as you change how you integrate with APIs.

Instead, Hoss recommends API consumers monitor each request as it happens. When you can look at every API call, you can always find the source of a user’s problem. Even better, widespread issues will come to your attention quickly, meaning you can put your days of learning about API failure from your users in the past.

See how Hoss gives you free visibility into the APIs you consume.

What Not to Do - The Worst Advice About Remote Work

Matt Hawkins — Thu, 28 May 2020 22:56:59 +0000

We’re several months into the COVID-19 pandemic – times are strange, and advice is everywhere. We spoke to seven developers about what they think is the worst advice they’re hearing right now and why. We’re considering this our what-not-to-do guide.

“That you should have a super strict work-life balance, work from 9 to 4:30 and have a shorter lunch. I think in today’s world, you have the opportunity to make your daily schedule work better for you. Ask yourself what times during the day you are really in flow or psyched to work. In my case, I’m really excited to write code after dinner.

I think the pandemic allows us a new way to envision the work-life balance that could make us all happier and more productive. Companies should realize there are potentially huge gains to be seen here.”

Michael Kennedy is the founder and host of Talk Python to Me, a weekly podcast about Python and related software developer topics. You can learn more about the Talk Python to Me podcast at talkpython.fm and follow Michael on Twitter at @mkennedy.

“That employers should be spying on their employees who are now at home to make sure they are working. People will always find a way to screw around on the job and no amount of mandatory web cameras or keyboard loggers of spyware on computers is going to change that. What is an employer going to do if I decide to go to the bathroom at home and bring my phone with me to play a game or do some other "non-work-related" task?”

Chris Hartjes has been building and testing web applications of all shapes and sizes since 1998, with a focus on best practices and how to use testing as an effective development tool. He is a senior test engineer at Mozilla and owner of Grumpy Learning, Inc.

“Setting the expectation that everything is normal at work because we’re privileged to be able to work from home is bad advice. It’s not normal. Forget about the absence of social interaction. What about all the daily habits that have been disrupted? How about all the different living situations? Parents at home? Roommates suddenly together 24/7? You might be comfy in your home office, but your co-workers might be living entirely different experiences. It’s not normal. Acknowledge that.”

Michael Lopp is the author of “The Art of Leadership: Small Things Done Well,” which uses stories from his professional experience at Netscape, Apple and Slack to present a series of small but compelling practices to help readers build leadership skills. Read Michael’s blog here and follow him on Twitter at @rands.

“Hearing people talking about pushing always-on camera feeds strikes me as misguided. Though there is virtue in trying to replicate the onsite experience of knowing someone is there and hearing the chatter and gaining context from the things happening around you, pressure to be on camera all the time feels authoritarian and runs counter to the remote-first ethos of interacting via chat and escalating the communication-medium bandwidth for interactions that need it. For remote work to function optimally, people need to feel trusted in that they are going to get the job done and that they are treated as adults.”

David Rael is a software developer and host of the Developer on Fire podcast, which tells the stories of some of the amazing people in software. Learn more about the Developer on Fire podcast here.

“I feel like there are a lot of people who just really want things to go back to the way they were – I see this on social media a lot. I think the reality is that things are never going to go back to the way they were before – there’s a new normal, and I think we just really have to accept it. The first few weeks we were on lockdown, I lost motivation and didn’t get a lot of work done. But about a week or two into it, I had a mental shift and just accepted that things are going to change both in my own life and at a macro level. Since then, I’ve been able to focus a lot better and move on. It’s important to accept that this isn’t business as usual, and things are going to change. We can’t go back to the way it was.”

Laurence Bradford is the creator of Learn to Code with Me, an online resource and podcast for beginners learning to code. You can learn more about Learn to Code with Me here and follow Laurence on Twitter at @learntocodewithme

“I see people who are starting their journey into software get so much advice about what to learn, in what order, and how quickly. I think we really risk overwhelming people when they start with the amount of different technologies they have to choose from. I think (maybe controversially!) it doesn't matter that much how someone gets started, or what language they pick to learn. Pick one, and dive in!”

Jack Franklin is a frontend engineer at Google and a blogger who writes about JavaScript, React, software development and more. He is also co-host of the web development podcast, Fish and Scripts. Read Jack’s blog here and follow him on Twitter at @Jack_Franklin.

“The worst advice I hear is that remote work, especially across timezones, is not efficient. In my opinion, the extra time is spent setting up software contracts, writing more documentation and tests, and working more methodically. These are all processes that we should be following anyways.”

Jason Gauci is a software engineering manager at Facebook AI where he leads ReAgent, a team that uses reinforcement learning to do automated marketing for billions of people. He is also the co-host of Programming Throwdown, a podcast that educates computer scientists and software engineers on a cavalcade of programming and tech topics. Learn more about Jason’s podcast here and follow him on Twitter at @NeuralNets4Life.

Read the full Dev Bites series here

The True Cost of Using Public APIs

Matt Hawkins — Tue, 19 May 2020 23:25:41 +0000

The True Cost of Using Public APIs

How ubiquitous are APIs in today’s development processes? Try asking an engineer how many APIs their project integrates. Most teams won’t know the answer. From analytics tools to maps and cloud hosting, modern applications use a hefty collection of internal and public APIs. Developers use these to quickly assemble applications that would otherwise take much more effort to build. However, there’s a forgotten expense not typically calculated early in a project.

When you add another API into your software, its impact is felt long after that initial integration. Developers also need to maintain the connections, which includes identifying issues as they arise. Too often, the problems don’t surface until a user reports a bug. For most companies, that’s way too late, but building tools to expose the problems is only an option for the most show stopping features.

In this post, we’ll look at the user experience of API errors—and just how common they are. And we’ll see what’s needed to reduce these API headaches.

How Customers Experience Broken Integrations

Modern applications rely on an army of APIs to bring quality features to their users. Whether the product is a web, desktop or mobile app, frontend or backend, the developer is going to rely heavily on the functionality of third party APIs. When these fail, customers cannot tell the difference between which errors to attribute to the developer and which to the third party. All they see is a broken application. One broken API can cause a bad customer experience, which can in turn lead to a direct loss in revenue.

For example, imagine you are creating a new bike sharing app. You’ll need to write plenty of original code, but you can also build on existing tools. In fact, most developers wouldn’t even try to recreate the most common infrastructure available via API.

Your app will likely need to integrate with:

Cloud hosting
Maps to show locations of bikes
Geocoding API to convert locations
Payments service
Communications services

If you’re going to share bikes, you obviously need to know where they are and share the data with your users. So, you might plot the bike locations on Google Maps. Depending on your monetization model, you might even need to track the distance between their pickup location and destination to charge them by the mile. If this is the case, your app also requires a payment system. Integrate Stripe for credit cards or take bank payments via Plaid, a financial services API which was recently acquired by Mastercard.

Even simple applications require functionality that adds up. You might need to send SMS or email. Or integrate a secure chat feature like you’d find on Lyft or Craigslist. Meanwhile, you can employ a service like SendGrid or MailChimp to automate email reminders and keep your customer base engaged.

Suddenly, you are sitting on a massively complex system which not only makes errors more difficult to track and mitigate, but also means your functionality relies on countless third parties to minimize and track their own errors. Users see one broken element of an app as indicative of a broken system.

Developers frequently monitor and address the performance of their own systems. This includes writing unit tests, paying down technical debt, and frequently reassessing functionality. Additionally, they might bring in quality assurance teams to look for user experience issues.

However, many teams fail to take these same measures to analyze their APIs. Without those measures, it’s easy for them to miss the ways APIs are impacting user experience. You should use the same rigor with integrations as you do with code you control. This way you can be immediately notified when response times spike or errors occur.

API Errors Happen More Than You Realize

As much as applications rely on public APIs, public APIs are notoriously unreliable. Each API has a number of ways to fail and most apps incorporate multiple APIs. You need to expect errors and ideally try to mitigate them. You cannot wait for users to report problems on their own. And waiting for errors to resolve themselves won’t work if your user has moved on. When customers encounter these sorts of roadblocks, they are not likely to investigate where the problem started.
SmartBear’s 2019 State of APIs report found that, “organizations that view API monitoring as a top priority are vastly outperforming those that do not at resolving performance problems.” The report attributes this to sky high customer expectations. Their survey found 57% of API consumers expect issues to be resolved in one day, and 40% expect a fix in 12 hours.

APIs can fail to return requests for a number of different reasons:

Response Time: In these days of high expectations, a slow app can be as bad as a broken app. Response time is also the canary in the coal mine that larger issues may be coming.
Mismatched Error Code: Proper status codes help adjust to API errors, but you can’t always count on the provider to send it. In some cases, you get a 200 -- meaning no error has occurred -- but the response still has error details. In these cases, a person surveying the data would be able to tell there is an issue, but the software doesn’t know to bring it up to anyone.
Authorization Credentials: APIs run authorization credentials on who is making a request in order to determine if the right person is getting information. This helps keep the system and your data secure, but also adds yet another layer where a valid request can be tripped up. Credentials can time out or be revoked, but a user only sees an error message and no explanation.
Rate Limits: Many APIs control the flow of traffic by implementing rate limits on requests. These might be on a daily basis or by the second. Building in logic to handle rate limits (i.e., 429 errors) is time consuming. It also creates much better experiences and decreases data loss when you can automatically retry.

While many developers incorporate some form of API monitoring, they aren’t always focused on external APIs. Too often, it requires teams to be proactive rather than reactive. That means you need to know exactly what errors to look for before they happen. You need to know about the errors you didn’t anticipate, too. Teams must be armed with these sorts of insights in order to meet user expectations.

What’s Needed to Eliminate API Headaches

Modern applications require numerous connections to other APIs to function. Like any complex machine, when one gear is out of place, the system breaks down. To identify and fix errors requires significant tooling around every API call you make. You need to go beyond monitoring, with retry logic and anomaly detection.

Being proactive about API maintenance means having an extreme awareness of your API network. Each time a user sends a request, you need to know how long it took and what data is returned. These insights help to predict when future errors may occur. Meanwhile, if the request returns an error, you must be able to look at the details of the request and respond swiftly. This way, the scope of API errors is limited to just a few users. Unfortunately, developers rarely have access to such intricate tooling. It is difficult to build in-house and consumes significant time and resources.

Hoss is focused on this problem. Hoss tracks and manages the APIs companies consume to help developers limit these hassles and avoid the damaging effects of poor API performance. The service provides a full, easy-to-understand dashboard of API analytics so developers can make better API-driven products and seamless user experiences. API proliferation has enormous benefits, but it also comes with costs – the developers who take action to mitigate those costs are best positioned to take advantage of the API boom.