You are here


Highlights from the Artificial Intelligence Conference in London 2018

O'Reilly Radar - Wed, 2018/10/10 - 13:00

Watch highlights from expert talks covering artificial intelligence, machine learning, automation, and more.

People from across the AI world came together in London for the Artificial Intelligence Conference. Below you'll find links to highlights from the event.

The state of automation technologies

Ben Lorica and Roger Chen highlight recent trends in data, compute, and machine learning.

AI in production: The droids you’re looking for

Jonathan Ballon explains why Intel’s AI and computer vision edge technology will drive advances in machine learning and natural language processing.

AI and machine learning at Amazon

Ian Massingham discusses the application of ML and AI within Amazon, from retail product recommendations to the latest in natural language understanding.

Why we built a self-writing Wikipedia

Amy Heineike explains how Primer created a self-updating knowledge base that can track factual claims in unstructured text.

Trust and transparency of AI for the enterprise

Ruchir Puri explains why trust and transparency are essential to AI adoption.

AI for a better world

Ashok Srivastava draws upon his cross-industry experience to paint an encouraging picture of how AI can solve big problems.

Rethinking software engineering in the AI era

Yangqing Jia talks about what makes AI software unique and its connections to conventional computer science wisdom.

Bringing AI into the enterprise: A functional approach to the technologies of intelligence

Kristian Hammond maps out simple rules, useful metrics, and where AI should live in the org chart.

Fireside chat with Marc Warner and Louis Barson

Marc Warner and Louis Barson discuss the internal and external uses of AI in the UK government.

Building artificial people: Endless possibilities and the dark side

Supasorn Suwajanakorn discusses the possibilities and the dark side of building artificial people.

Deep learning at scale: A field manual

Jason Knight offers an overview of the state of the field for scaling training and inference across distributed systems.

The missing piece

Cassie Kozyrkov shares machine learning lessons learned at Google and explains what they mean for applied data science.

Notes from the frontier: Making AI work

Drawing on the McKinsey Global Institute’s research, Michael Chui explores commonly asked questions about AI and its impact on work.

Continue reading Highlights from the Artificial Intelligence Conference in London 2018.

Categories: Technology

Rethinking software engineering in the AI era

O'Reilly Radar - Wed, 2018/10/10 - 13:00

Yangqing Jia talks about what makes AI software unique and its connections to conventional computer science wisdom.

Continue reading Rethinking software engineering in the AI era.

Categories: Technology

AI and machine learning at Amazon

O'Reilly Radar - Wed, 2018/10/10 - 13:00

Ian Massingham discusses the application of ML and AI within Amazon, from retail product recommendations to the latest in natural language understanding.

Continue reading AI and machine learning at Amazon.

Categories: Technology

AI in production: The droids you’re looking for

O'Reilly Radar - Wed, 2018/10/10 - 13:00

Jonathan Ballon explains why Intel’s AI and computer vision edge technology will drive advances in machine learning and natural language processing.

Continue reading AI in production: The droids you’re looking for.

Categories: Technology

AI for a better world

O'Reilly Radar - Wed, 2018/10/10 - 13:00

Ashok Srivastava draws upon his cross-industry experience to paint an encouraging picture of how AI can solve big problems.

Continue reading AI for a better world.

Categories: Technology

Four short links: 10 October 2018

O'Reilly Radar - Wed, 2018/10/10 - 03:55

Better Education, Do You Need Blockchain?, Visualization Book, and Hiring Coders

  1. Generation of Greatness (Edwin Land) -- eye-wateringly sexist on the surface but (if you replace "boys" with "children" and "men" with "people") an astonishingly forward-thinking piece on education. I'd want to hire graduates of this approach. (via Javier Candero)
  2. Do You Need Blockchain? Flowchart -- from page 42 of the Blockchain Technology Overview report from NIST.
  3. Visualization Analysis and Design (Amazon) -- Tamara Munzner's systematic, comprehensive framework for thinking about visualization in terms of principles and design choices. The book features a unified approach, encompassing information visualization techniques for abstract data, scientific visualization techniques for spatial data, and visual analytics techniques for interweaving data transformation and analysis with interactive visual exploration. It emphasizes the careful validation of effectiveness and the consideration of function before form. (via review)
  4. Assessing Software Engineering Candidates (Bryan Cantrill) -- Joyent's guidance, originally published as a company RFD. While we advocate (and indeed, insist upon) interviews, they should come relatively late in the process; as much assessment as possible should be done by allowing the candidate to show themselves as software engineers truly work: on their own, in writing.

Continue reading Four short links: 10 October 2018.

Categories: Technology

What we learn from AI's biases

O'Reilly Radar - Tue, 2018/10/09 - 04:00

Our bad AI could be the best tool we have for understanding how to be better people.

In "How to Make a Racist AI Without Really Trying," Robyn Speer shows how to build a simple sentiment analysis system, using standard, well-known sources for word embeddings (GloVe and word2vec), and a widely used sentiment lexicon. Her program assigns "negative" sentiment to names and phrases associated with minorities, and "positive" sentiment to names and phrases associated with Europeans. Even a sentence like "Let's go get Mexican food" gets a much lower sentiment score than "Let's go get Italian food." That result isn't surprising, nor are Speer's conclusions: if you take a simplistic approach to sentiment analysis, you shouldn't be surprised when you get a program that embodies racist, discriminatory values. It's possible to minimize algorithmic racism (though possibly not eliminate it entirely), and Speer discusses several strategies for doing so.

I want to look at this problem the other way around. There's something important we can learn from this experiment, and from other examples of AI "gone wrong." AI never "goes wrong" on its own; all of our AI systems are built by humans, and reflect our values and histories.

What does it mean when you build an AI system in the simplest possible way that you end up with a racially biased result? I don't think many AI developers would build such systems intentionally. I am willing to believe that many are naive and take free data sources at face value. That is exactly what is happening here: GloVe, a widely used collection of word embeddings, brings a lot of baggage with it, as does word2vec. But, just as programmers are more likely to be naive than evil, I don't think GloVe was built by people trying to perpetuate stereotypes. They just collected English language samples. They're a reflection of language as it is used.

All of which means we're facing a deeper problem. Yes, Speer's naive sentiment analysis is racist, but not because of the algorithm. It's because of the data; and not because the data is wrong, but because the data is right. The data wasn't collected with malice aforethought; it just reflects how we use language. Our use of language is full of racial biases, prejudices, and stereotypes. And while I would not recommend that anyone build and deploy a naive system, I appreciate examples like this because they hold up a mirror to our own usage. If we're willing to listen, they teach us about the biases in our own speech. They're metrics for our own poor performance.

Fairness is, by nature, aspirational: it's forward-looking. We want to be fair; we rarely look at the past and take pride in how fair we were. Data is always retrospective; you can't collect data from the future. Every datum we have reflects some aspect of the past, which means it almost always reflects history of prejudice and racism, both overt and covert. Our language is likely to be a better metric for our attitudes than any public opinion poll. Nobody thinks they are a racist; but our language says otherwise, and our algorithms reflect that.

We can (and we need to) analyze almost every example of algorithmic unfairness in this way. COMPAS, the tool for recommending bail and jail sentences, reflects a history of law enforcement that has fallen much more heavily on minorities. Minorities don't often get second chances; they don't get policemen who look the other way after saying "aw, he's basically a good kid" or "don't let me catch you doing that again." Poor urban neighborhoods get labeled "high risk zones," though if you look at a map of white collar crime, you'll see something much different. While COMPAS is a bad tool in the courtroom, it's an excellent tool for understanding the reality of how law enforcement works, and it's unfortunate it hasn't been used that way. (It might also be less unfair than predominantly white judges and juries, but that's another question.) Many of the problems around face recognition for dark-skinned people arise because cameras have long been designed to optimize for light skin tones. That's less a reflection on our technical capabilities than our cultural priorities. Amazon's initial same-day delivery service, which excluded heavily black and hispanic neighborhoods, doesn't reflect some evil intent; it reflects a long history of red-lining and other practices that forced minorities into ghettos. Exclusion jumped out of the data, and it's important to understand the histories that gave us that data.

When you get to the bottom of it, these aren't problems with the algorithms, or even with the data; they're problems with the ultimate source of the data, and that's our own actions. If we want better AI, we must be better people. And some of our bad AI could be the best tool we have for understanding how to be better people.

Continue reading What we learn from AI's biases.

Categories: Technology

Four short links: 9 October 2018

O'Reilly Radar - Tue, 2018/10/09 - 03:55

Lost Lessons, Metaphors to Monads, Future of Work, and Awesome Starts at The Top

  1. Neither Paper Nor Digital Does Reading Well -- Develop a familiarity with, for example, Alan Kay’s or Douglas Engelbart’s visions for the future of computing and you are guaranteed to become thoroughly dissatisfied with the limitations of every modern OS. Reading up hypertext theory and research, especially on hypertext as a medium, is a recipe for becoming annoyed at The Web. Catching up on usability research throughout the years makes you want to smash your laptop agains the wall in anger. And trying to fill out forms online makes you scream "it doesn’t have to be this way!" at the top of your lungs. That software development doesn’t deal with research or attempts to get at hard facts is endemic to the industry. (via Daniel Siegel)
  2. The Unreasonable Effectiveness of Metaphor (YouTube) -- Julia Moronuki, author of Haskell from First Principles, sneaks up on the idea of monads by starting with how linguists and cognitive scientists understand metaphors. (via @somegoob)
  3. World Development Report 2019: The Changing Nature of Work -- In countries with the lowest human capital investments today, our analysis suggests that the workforce of the future will only be one-third to one-half as productive as it could be if people enjoyed full health and received a high-quality education.
  4. Chairman of Nokia Learned Deep Learning -- I realized that as a long-time CEO and chairman, I had fallen into the trap of being defined by my role: I had grown accustomed to having things explained to me. Instead of trying to figure out the nuts and bolts of a seemingly complicated technology, I had gotten used to someone else doing the heavy lifting. [...] After a quick internet search, I found Andrew Ng’s courses on Coursera, an online learning platform. Andrew turned out to be a great teacher who genuinely wants people to learn. I had a lot of fun getting reacquainted with programming after a break of nearly 20 years. Once I completed the first course on machine learning, I continued with two specialized follow-up courses on deep learning and another course focusing on convolutional neural networks, which are most commonly applied to analyzing visual imagery. Yow.

Continue reading Four short links: 9 October 2018.

Categories: Technology

Meeting info for 10/11

PLUG - Mon, 2018/10/08 - 11:35
This month we will get an introduction to the command line from Ryan Hermens.  This would be a good meeting to bring friends and family that have an interest in Linux.

Ryan Hermens: Command Line Tools Seminar

This seminar will be an interactive presentation on core command lines tools. It is aimed at the beginner to help users make the jump from GUI tools to using the power of the command line. Examples of some of the subjects covered include package managers, linux permissions, users and groups, navigating the file system, creating and editing files, background and foreground job management, linux signals, and more. To get the most out of this seminar, please come with a laptop with Linux already installed.

Ryan has 7 years of experience doing devops work, ranging from full stack development to cybersecurity operations. He has worked for Microchip, Intel, and Charles Schwab. Currently, he works with Truveris acting as lead security engineer. He holds degrees in both Computer Science and Computer Systems Engineering from Arizona State University, graduating magna cum laude.

Four short links: 8 October 2018

O'Reilly Radar - Mon, 2018/10/08 - 04:10

Stripe Stats, Worker Ethics, FPGA Futures, and Internet Archive Stats

  1. The Story of Stripe (Wired UK) -- Over the past year, 65% of UK internet users and 80% of U.S. users have bought something from a Stripe-powered business.
  2. Tech Workers Want to Know: What Are We Building This For? (NYT) -- about time. I see plenty of places mandating their young kids are taught coding. Who's mandating their coders take ethics classes so they have an ability to think critically about the applications of what they develop?
  3. Inference: The Future of FPGA (Next Platform) -- Inference, which is almost exclusively run on Xeon servers in the data center these days, therefore represents maybe 1% of the workload in the server installed base and has driven a little less than 1% of the server spending, by our math. [...] But as organizations figure out how to use machine learning frameworks to build neural networks and then algorithms that they embed into their applications, there will be a lot more inference going on, and this will become a representative workload driving a lot of chip revenues.
  4. Internet Archive Stats -- 22PB of Internet Archive growing 4PB/y, including four million books, 200 million hours of broadcast news, and 300,000 playable classic video games, 1.5 billion pages crawled/week, 200 staffers.

Continue reading Four short links: 8 October 2018.

Categories: Technology

Four short links: 5 October 2018

O'Reilly Radar - Fri, 2018/10/05 - 03:55

Supply Chain Security, ML in FB Marketplace, Datasette Ideas, and Scraper DSL

  1. Motherboard Supply Chain Compromise (Bloomberg) -- fascinating story of Chinese compromise of SuperMicro motherboards, causing headaches for AWS, Apple, and the U.S. military, among many others. See also tech for spotting these things and some sanity checking on the article's claims.
  2. How Facebook Marketplace Uses Machine Learning -- nice. It's increasingly clear there's not much that's user-facing that can't benefit from machine learning to prompt, augment, and check user input.
  3. Interesting Ideas in Datasette (Simon Willison) -- solid technical reflection on non-obvious approaches and techniques in his project.
  4. Ferret -- interesting approach: a DSL for writing web scrapers.

Continue reading Four short links: 5 October 2018.

Categories: Technology

Four short links: 4 October 2018

O'Reilly Radar - Thu, 2018/10/04 - 03:20

Autonomy and UI, Replicating ML Research, FPGA Dev, and Standard Notes

  1. UI for Self-Driving Cars -- I'd never thought about it, but Ford has: how does a self-driving car signal its intentions to humans (and/or other autonomous vehicles around)? Through our testing, we believe these signals have the chance to become an accepted visual language that helps address an important societal issue in how self-driving vehicles interact with humans.
  2. Reproducing Machine Learning Research -- there's good news—reproducibility breaks down in three main places: the code, the data, and the environment. I’ve put together this guide to help you narrow down where your reproducibility problems are, so you can focus on fixing them.
  3. Open Source FPGA Dev Guide -- in case you've been curious about kicking the tires. (Yes, I know FPGAs don't have tires, please don't write in.)
  4. Standard Notes -- what to use if you're nervous about entrusting your data to someone else's product roadmap (EverNote or OneNote or Keep). Free, open source, and completely encrypted. Ticks all the boxes: 2FA, automated backups to cloud storage, versioning, cross-platform (Mac, Windows, iOS, Android, Linux), offline access...

Continue reading Four short links: 4 October 2018.

Categories: Technology

Experts reveal infrastructure trends to watch

O'Reilly Radar - Thu, 2018/10/04 - 03:00

A new report examines the state of infrastructure and anticipated near-term developments through the eyes of infrastructure experts.

Trends like server virtualization, containers, serverless, and hardware abstraction are shifting the infrastructure landscape. Functions as a service (FaaS) and infrastructure as a utility are also gaining traction. These changes mean infrastructure experts and the organizations that employ them must evolve as the industry evolves.

With that in mind, O’Reilly recently examined the state of infrastructure and anticipated near-term developments through the eyes of infrastructure experts. In the resulting free report, “Infrastructure Now 2018,” the collected insights from these experts highlight what matters now and what's around the corner.

Takeaways from the report include:

  • Democratization and standardization—while ensuring security—are key to successfully keeping pace with evolving infrastructure. Whether you’re building tools or choosing new technology to work into your platform, the tools must be accessible to a wide range of skill sets, compatible with (or easily ingested into) existing systems, and cost effective.
  • Reducing complexity is the overwhelming trend expected in the next 10 years: from containers and serverless, to cloud services, to “easily composable business applications,” the infrastructure-as-a-service (IaaS) movement is expected to continue and expand.
  • Evolving infrastructure and the trend toward abstraction is going to require changes in roles for people in DevOps, Site Reliability Engineering (SRE), and operations positions. This shift is largely looked upon with optimism, but the experts anticipate a move away from specialized positions toward a need for generalists and full-stack engineers.
  • Not everyone interviewed for the report agreed, but it appears legacy infrastructure is here to stay, and new legacy infrastructure woes are anticipated. One expert predicts “a spaghetti ball of interconnected microservices,” and another pointed out that “everything becomes legacy as soon as it hits production.”
  • Improvements in containers and serverless technology top the list of expectations for the next 12 months. Some experts are already seeing signs that infrastructure as a utility is imminent.

For more on these topics and other key infrastructure issues, download the full report.

Continue reading Experts reveal infrastructure trends to watch.

Categories: Technology

Practical ethics

O'Reilly Radar - Wed, 2018/10/03 - 13:00

Laura Thomson shares Mozilla’s approach to data ethics, review, and stewardship.

Continue reading Practical ethics.

Categories: Technology

O’Reilly Radar: Systems engineering tool trends

O'Reilly Radar - Wed, 2018/10/03 - 13:00

Roger Magoulas shares insights from O'Reilly's online learning platform that point toward shifts in the systems engineering ecosystem.

Continue reading O’Reilly Radar: Systems engineering tool trends.

Categories: Technology

Chaos Day: When reliability reigns

O'Reilly Radar - Wed, 2018/10/03 - 13:00

Tammy Butow explains how companies can use Chaos Days to focus on controlled chaos engineering.

Continue reading Chaos Day: When reliability reigns.

Categories: Technology

Critical path-driven development

O'Reilly Radar - Wed, 2018/10/03 - 13:00

Jaana Dogan explains why Google teaches its tracing tools to new employees and how it helps them learn about Google-scale systems end to end.

Continue reading Critical path-driven development.

Categories: Technology

Why marketing matters

O'Reilly Radar - Wed, 2018/10/03 - 13:00

Michael Bernstein offers an unflinching look at some of the fallacies that developers believe about marketing.

Continue reading Why marketing matters.

Categories: Technology

Best design practices to get the most out of your API

O'Reilly Radar - Wed, 2018/10/03 - 04:05

Practical techniques to ensure developers can actually do the things you want them to do using your API.

In the previous chapters, we gave an overview of various approaches for transmitting data via your web API. Now that you're familiar with the landscape of transport and have an understanding of how to choose between various patterns and frameworks, we want to provide some tactical best practices to help your developers get the most out of your API.

Designing for Real-Life Use Cases

When designing an API, it’s best to make decisions that are grounded in specific, real-life use cases. Let’s dig into this idea a bit more. Think about the developers who are using your API. What tasks should they be able to complete with your API? What types of apps should developers be able to build? For some companies, this is as targeted as “developers should be able to charge customer credit cards.” For other companies, the answer can be more open-ended: “developers should be able to create a full suite of interactive consumer-quality applications.”

After you have your use cases defined, make sure that developers can actually do the things you want them to do using your API.

Quite often APIs are designed based on the internal architecture of the application, leaking details of the implementation. This leads to confusion for third-party developers and a bad developer experience. That’s why it’s so important to focus not on exposing on your company’s internal infrastructure but on the experience that an outside developer should have when interacting with your API. For a concrete example of how to define key use cases, see the section “Outline Key Use Cases.”

When you get started with a design, it’s easy to imagine many “what-ifs” before implementation and testing. Although these questions are useful during the brainstorming phase, they can lead a design astray by tempting you to try and solve too many problems at once. By picking a specific workflow or use case, you will be able to focus on one design and then test whether it works for your users.

Expert Advice

When we asked Ido Green, developer advocate at Google, what makes an API good, his top answer was focus:

"The API should enable developers to do one thing really well. It’s not as easy as it sounds, and you want to be clear on what the API is not going to do as well.”

Designing for a Great Developer Experience

Like we spend time thinking about the user experience delivered via a user interface, it's important to think about the developer experience delivered via an API. Developers have a low bar for abandoning APIs, so bad experiences result in attrition. By the same token, usability is the bare minimum for keeping a developer using your API. Good experiences get love from developers: they will in turn, become the most creative innovators using your API as well as evangelists for your API.

Make It Fast and Easy to Get Started

It’s important for developers to be able to understand your API and to get up and running quickly. Developers may be using your API to avoid having to build out a secondary product suite to support their main product. Don’t make them regret that decision with an API that's opaque and difficult to use.

Expert Advice

No matter how carefully we design and build our core API, developers continue to create products we’d never expect. We give them the freedom to build what they like.

Designing an API is much like designing a transportation network. Rather than prescribing an end state or destination, a good API expands the very notion of what’s possible for developers.

—Romain Huet, head of developer relations at Stripe

Documentation can go a long way toward helping developers get started. In addition to documents that outline the specifications of an API, it can be helpful to have tutorials or Getting Started guides. A tutorial is an interactive interface to teach developers about your API. You might have developers answer questions or fill in “code” in an input area. A guide is a more contextual document than a specification. It provides information for developers at a certain point in time—typically when getting started, but sometimes when updating or converting from one version or feature to another.

In some cases, you can supplement the ease of use by providing interactive documentation online, where developers have a sandbox to test out your API. Oftentimes, developers can use these interfaces to test code and preview results without having to implement authentication.

Figure 1-1. Developers can try the Stripe API without signing up

In addition to interactive documentation, tools such as software development kits (SDKs) can go a long way toward helping developers use your API. These code packages are designed to help developers get up and running quickly with their projects by simplifying some of the transactional layers and setup of an application.

For an ideal experience, developers should be able to try out your APIs without logging in or signing up. If you cannot avoid that, you should provide a simple signup or application creation flow that captures the minimum required information. If your API is protected by OAuth, you should provide a way for developers to generate access tokens in the UI. Implementing OAuth is cumbersome for developers, and in the absence of easy ways to generate these tokens, you will see a significant drop-off rate at this point.

Work Toward Consistency

You want your API to be intuitively consistent. That should be reflected in your endpoint names, input parameters, and output responses. Developers should be able to guess parts of your API even without reading the documentation. Unless you are making a significant version bump or large release, it's best to work toward consistency when designing new aspects of an existing API.

For example, you might have previously named a group of resources “users” and named your API endpoints accordingly, but you now realize that it makes more sense to call them “members.” It can be very tempting to work toward the “correctness” of the new world rather than focus on consistency with the old. But if the objects are the same, it could be very confusing to developers to sometimes refer to them as “users” and other times as “members” in URI components, request parameters, and elsewhere. For the majority of incremental changes, consistency with the existing design patterns will work best for your users.

As another example, if in some places you have a response field called user and sometimes its type is an integer ID but sometimes its type is an object, each and every developer receiving those two response payloads needs to check whether user is an int ID or an object. This logic leads to code bloat in developers’ code bases, which is a suboptimal experience.

This can show up in your own code as well. If you have SDKs that you’re maintaining, you will need to add more and more logic to handle these inconsistencies and to make a seamless interface for developers. You might as well do this at the API level by maintaining consistency instead of introducing new names for the same things.

Consistency generally means that there are a number of patterns and conventions repeated throughout your API, in such a way that developers can begin to predict how to use your API without seeing the documentation. That could include anything from data access patterns to error handling to naming. The reason consistency is important is that it reduces the cognitive load on developers who are trying to figure out your API. Consistency helps your existing developers in adapting new features by reducing forks in their code, and it helps new developers hit the ground running with everything you’ve built on your API. In contrast, with less consistency, different developers will need to reimplement the same logic over and over again.

Make Troubleshooting Easy

Another best practice for designing APIs is making troubleshooting easy for developers. This can be done through returning meaningful errors as well as by building tooling.

Meaningful errors

What’s in an error? An error can occur in many places along your code path, from an authorization error during an API request, to a business logic error when a particular entity doesn’t exist, to a lower-level database connection error. When designing an API, it is helpful to make troubleshooting as easy as possible by systematically organizing and categorizing errors and how they are returned. Incorrect or unclear errors are frustrating and can negatively affect adoption of your APIs. Developers can get stuck and just give up.

Meaningful errors are easy to understand, unambiguous, and actionable. They help developers to understand the problem and to address it. Providing these errors with details leads to a better developer experience. Error codes that are machine-readable strings allow developers to programmatically handle errors in their code bases.

In addition to these strings, it is useful to add longer-form errors, either in the documentation or somewhere else in the payload. These are sometimes referred to as human-readable errors. Even better, personalize these errors per developer. For instance, with the Stripe API, when you use a test key in your live mode, it returns an error such as:

No such token tok_test_60neARX2. A similar object exists in test mode, but a live mode key was used to make this request. Table 1-1. Example error codes for different situations Situation Recommended Not recommended Authentication failed because token is revoked token_revoked invalid_auth Value passed for name exceeded max length name_too_long invalid_name Credit card has expired expired_card invalid_card Cannot refund because a charge has already been refunded charge_already_refunded cannot_refund

To begin designing your system of errors, you might map out your backend architecture along the code path of an API request. The goal of this is not to expose your backend architecture but to categorize the errors that happen and to identify which ones to expose to developers. From the moment an API request is made, what are the critical actions that are taken to fulfill the request? Map out the various high-level categories of errors that occur during the course of an API request, from the beginning of the request to any service boundaries within your architecture.

Table 1-2. Group errors into high-level categories Error category Examples System-level error

Database connection issue

Backend service connection issue

Fatal error

Business logic error


Request fulfilled, but no results were found

Business-related reason to deny access to information

API request formatting error

Required request parameters are missing

Combined request parameters are invalid together

Authorization error

OAuth credentials are invalid for request

Token has expired

After grouping your error categories throughout your code path, think about what level of communication is meaningful for these errors. Some options include HTTP status codes and headers, as well as machine-readable “codes” or more verbose human-readable error messages returned in the response payload. Keep in mind that you’ll want to return an error response in a format consistent with your non-error responses. For example, if you return a JSON response on a successful request, you should ensure that the error is returned in the same format.

You might also want a mechanism to bubble up errors from a service boundary to a consistent format from your API output. For example, a service you depend on might have a variety of connection errors. You would let the developer know that something went wrong and that they should try again.

In most cases, you want to be as specific as possible to help your developers take the correct next course of action. Other times, however, you might want to occlude the original issue by returning something more generic. This might be for security reasons. For example, you probably don’t want to bubble up your database errors to the outside world and reveal too much information about your database connections.

Table 1-3. Organize your errors into status codes, headers, machine-readable codes, and human-readable strings Error category HTTP status HTTP headers Error code (machine-readable) Error message (human-readable) System-level error 500 -- -- -- Business logic error 429 Retry-After rate_limit_exceeded “You have been rate-limited. See Retry-After and try again.” API request formatting error 400 -- missing_required_parameter “Your request was missing a {user} parameter.” Auth error 401 -- invalid_request “Your ClientId is invalid.”

As you begin to organize your errors, you might recognize patterns around which you can create some automatic messaging. For example, you might define the schema for your API to require specific parameters and to have a library that automatically checks for these at the beginning of the request. This same library could format the verbose error in the response payload.

You’ll want to create a way to document these errors publicly on the web. You can build this into your API description language or documentation mechanism. Think about the various layers of errors before writing the documents, because it can become complicated to describe multiple factors if there are many different types of errors. You might also want to consider using verbose response payloads to link to your public documentation. This is where you’ll give developers more information on the error they received as well as how to recover from it.

For even more structured and detailed recommendations on meaningful errors and problem details for HTTP APIs, see RFC 7807.

Build tooling

In addition to making troubleshooting easy for developers, you should make it easy for yourself by building internal and external tools.

Logging on HTTP statuses, errors and their frequencies, and other request metadata is valuable to have, for both internal and external use, when it comes to troubleshooting developer issues. There are many off-the-shelf logging solutions available. However, when implementing one, before you troubleshoot real-time traffic, be sure to respect customer privacy by redacting any personally identifiable information (PII).

Figure 1-2. The Stripe API dashboard with request logs

Besides logging, when building an API, it’s helpful to create dashboards to help developers analyze aggregate metadata on API requests. For example, you could use an analytics platform to rank the most-used API endpoints, identify unused API parameters, triage common errors, and define success metrics.

Like for logging, many analytics platforms are available off the shelf. You can present the information in high-level dashboards that provide a visual display in a time-based manner. For example, you might want to show the number of errors per hour over the past week. Additionally, you might want to provide developers complete request logs with details about the original request, whether it succeeded or failed, and the response returned.

Make Your API Extensible

No matter how well you’ve designed your API, there will always be a need for change and growth as your product evolves and developer adoption increases. This means that you need to make your API extensible by creating a strategy for evolving it. This enables you as the API provider and your developer ecosystem to innovate. Additionally, it can provide a mechanism to deal with breaking changes. Let’s dive into the idea of extensibility and explore how to incorporate early feedback, versioning an API, and maintaining backward compatibility.

Expert Advice

APIs should provide primitives that can enable new workflows and not simply mirror the workflows of your application. The creation of an API acts as a gate for what the API’s users can do. If you provide too low-level access, you could end up with a confusing integration experience and you push too much work on the integrators. If you provide too high-level access, you could end up with most integrations simply mirroring what your own application does. You need to find the right balance to enable workflows you hadn’t considered either as part of your application or within the API itself in order to enable innovation. Consider what your own engineers would want in an API to build the next interesting feature for your application and then make that a part of your public API.

—Kyle Daigle, director of ecosystem engineering at GitHub

One aspect of extensibility is ensuring that you have created an opportunity for feedback with your top partners. You need a way to release certain features or fields and to give certain privileged developers the option to test these changes without releasing the changes to the public. Some would call this a “beta” or “early adopter” program. This feedback is extremely valuable in helping you decide whether your API has been designed in a way that achieves its goals. It gives you a chance to make changes before adoption has become prevalent and before significant changes require a lot of communication or operational overhead.

In some cases, you might want to version your API. Building a versioning system is easier if it’s baked into the design at an early stage. The longer you wait to implement versioning, the more complicated it becomes to execute. That's because it becomes more and more difficult as time goes on to update your code base’s dependency patterns so that old versions maintain backward compatibility. The benefit of versioning is that it allows you to make breaking changes with new versions while maintaining backward compatibility for old versions. A breaking change is a change that, when made, would stop an existing app from continuing to function as it was functioning before using your APIs.

Storytime: Slack's Translation Layer

In 2017 Slack launched its Enterprise Grid product, which was a federated model of its previous offering. As a result of this federation, Slack had to fundamentally change its user data model so that users could belong to multiple “workspaces.”

In the API, users previously had only a single ID. However, in the new federated model, each user had a main (global) user ID for the Enterprise Grid and a local user ID for each workspace. When existing teams migrated to the Enterprise Grid product, their user IDs were slated to change. This would have broken any third-party apps relying on a fixed user ID in the API.

When Slack's engineering team realized this problem, it went back to the drawing board to figure out what could be done to maintain backward compatibility for third-party developers. That’s when the team decided to create a translation layer. This additional infrastructure would silently translate user IDs to be consistent with the ones that developers had previously received.

Although the decision to build this translation layer delayed the Enterprise Grid product launch by several months, it was mission-critical for Slack to ensure that its API remained backward compatible.

For companies and products that businesses rely on, maintaining backward-compatible versions is a difficult requirement. That’s especially true for apps that don’t experience a high rate of change. For a lot of enterprise software, there isn’t somebody dedicated to updating versions, and there’s no incentive for a company to invest in updating versions just because you've released a new one. Many internet-connected hardware products also use APIs, but hardware does not always have a mechanism to update its software. Plus, hardware can be around for a long time—think about how long you owned your last TV or router. For those reasons, it is sometimes imperative that you maintain backward compatibility with previous API versions.

That said, maintaining versions does have a cost. If you don’t have the capacity to support old versions for years, or if you anticipate very few changes to your API, by all means skip the versions and adopt an additive change strategy that also maintains backward compatibility in a single, stable version.

If you anticipate major breaking changes and updates at any time in your future, we strongly recommend setting up a versioning system. Even if it takes years to get to your first major version change, at least you’ve got the system ready to go. The overhead of creating a system of version management at the beginning is much lower than that of adding it in later, when it's urgently needed.

Storytime: Deprecating an API at Twitch

In 2018, online video streaming platform Twitch decided to deprecate an API and provide a new API. After it announced the old API's deprecation and end of life (shutdown), Twitch received a lot of feedback from developers who said that they needed more time to handle the breaking change or their integrations would be broken. Because of that feedback, Twitch decided to extend the end of life of the old API to give developers ample time to move their code to the new one.

Closing Thoughts

Meeting the needs of your users is at the core of solid API design. In this chapter, we covered a number of best practices to help you achieve a great developer experience.

As you build your API and developer ecosystem, you might discover more best practices specific to your company, your product, and your users.

Continue reading Best design practices to get the most out of your API.

Categories: Technology

Four short links: 3 October 2018

O'Reilly Radar - Wed, 2018/10/03 - 03:55

Positive Chatbot, Inside Serverless, TimBL's Next Project, and Voting Machines

  1. Ixy -- chat with a bot that helps you not descend into irate internet madness. Nifty idea! (via Evan Prodromou)
  2. Peeking Behind the Curtains of Serverless Platforms -- interesting implementation details. We characterize performance in terms of scalability, coldstart latency, and resource efficiency, with highlights including that AWS Lambda adopts a bin-packing-like strategy to maximize VM memory utilization, that severe contention between functions can arise in AWS and Azure, and that Google had bugs that allowed customers to use resources for free.
  3. Solid -- Tim Berners-Lee's new open source project (and startup), building apps from linked data.
  4. DEFCON Voting Machines Report -- tl;dr: online voting is a disaster-in-waiting, a calamity of vulnerabilities that shabby-suited shysters would be afraid to peddle but which our local and central governments have embraced. Those who are willing to trade the integrity of their democracy for the false promise of increased voter turnout deserve neither. It is noteworthy that this year the defenses of the virtual election office were fortified using Israeli military defense software, while attack tools were limited to what is available with Kali Linux

Continue reading Four short links: 3 October 2018.

Categories: Technology


Subscribe to LuftHans aggregator - Technology