ThoughtWorks
  • Contacto
  • Português
  • Deutsch
  • English
  • 中文
Visión general
  • Cultura de ingeniería, mentalidad de entrega

    Adopta un enfoque moderno para el desarrollo de software y entrega valor más rápido.

    Toma de desiciones Inteligentes

    Aprovecha los resultados de tus datos para descubrir nuevas fuentes de valor

  • Modelo Operativo sin Frincción

    Mejora la habilidad de tu empresa para adaptarse al cambio

    Estrategia de Plataforma

    Crea plataformas tecnológicas que de adapten a su estrategia de negocio

  • Experience Design y Product Capabilities

    Diseña, entrega y evoluciona rápidamente productos y experiencias excepcionales

    Asociaciones

    Aprovechar nuestra red de socios confiables para ampliar los resultados que brindamos a nuestros clientes

Visión general
  • Sector Automotriz
  • Cleantech y Servicios Públicos
  • Servicios Financieros y Aseguradoras
  • Servicios Médicos
  • Medios y Publicidad
  • Organizaciones sin fines de lucro
  • Sector Público
  • E-commerce y Retail
  • Viajes y Transporte
Visión general

Destacados

  • Tecnología

    Una exploración profunda de tecnología empresarial y excelencia en ingeniería

  • Negocios

    Mantenerse actualizado con los últimos insights empresariales y de industria para líderes digitales

  • Cultura

    El espacio para encontrar contenido y tips de desarrollo profesional, y nuestra visión sobre la justicia social y la inclusión

Publicaciones Digitales y Herramientas

  • Radar Tecnológico

    Nuestra guía de tendencias tecnológicas actuales

  • Opiniones

    Una publicación para líderes digitales

  • Digital Fluency Model

    Un modelo para priorizar las capacidad digitales necesarias para navegar en la incertidumbre

  • Decoder

    Una guía tecnológica de la A a la Z para líderes de negocio

Todos los Insights

  • Artículos

    Opiniones profesionales que ayudarán al crecimiento de tu negocio

  • Blogs

    Opiniones personales de ThoughtWorkers de todo del mundo

  • Libros

    Navega a través de nuestra extensa biblioteca

  • Podcasts

    Emocionantes charlas sobre las últimas tendencias en negocios y tecnología

Visión general
  • Proceso de Aplicación

    Descubre lo que te espera durante nuestro proceso de selección

  • Graduados y cambio de carreras

    Empieza tu carrera en tecnología con el pie derecho

  • Ofertas de trabajo

    Encuentra puestos vacantes en tu región

  • Mantente conectado

    Suscríbete a nuestro boletín mensual

Visión general
  • Conferencias y eventos
  • Diversidad e Inclusión
  • Noticias
  • Código abierto
  • Nuestros líderes
  • Cambio Social
  • Português
  • Deutsch
  • English
  • 中文
ThoughtWorksMenú
  • Cerrar   ✕
  • Nuestros Servicios
  • ¿Con quién trabajamos?
  • Insights
  • Carreras
  • Acerca de Nosotros
  • Contacto
  • Regresar
  • Cerrar   ✕
  • Visión general
  • Cultura de ingeniería, mentalidad de entrega

    Adopta un enfoque moderno para el desarrollo de software y entrega valor más rápido.

  • Experience Design y Product Capabilities

    Diseña, entrega y evoluciona rápidamente productos y experiencias excepcionales

  • Modelo Operativo sin Frincción

    Mejora la habilidad de tu empresa para adaptarse al cambio

  • Toma de desiciones Inteligentes

    Aprovecha los resultados de tus datos para descubrir nuevas fuentes de valor

  • Asociaciones

    Aprovechar nuestra red de socios confiables para ampliar los resultados que brindamos a nuestros clientes

  • Estrategia de Plataforma

    Crea plataformas tecnológicas que de adapten a su estrategia de negocio

  • Regresar
  • Cerrar   ✕
  • Visión general
  • Sector Automotriz
  • Cleantech y Servicios Públicos
  • Servicios Financieros y Aseguradoras
  • Servicios Médicos
  • Medios y Publicidad
  • Organizaciones sin fines de lucro
  • Sector Público
  • E-commerce y Retail
  • Viajes y Transporte
  • Regresar
  • Cerrar   ✕
  • Visión general
  • Destacados

  • Tecnología

    Una exploración profunda de tecnología empresarial y excelencia en ingeniería

  • Negocios

    Mantenerse actualizado con los últimos insights empresariales y de industria para líderes digitales

  • Cultura

    El espacio para encontrar contenido y tips de desarrollo profesional, y nuestra visión sobre la justicia social y la inclusión

  • Publicaciones Digitales y Herramientas

  • Radar Tecnológico

    Nuestra guía de tendencias tecnológicas actuales

  • Opiniones

    Una publicación para líderes digitales

  • Digital Fluency Model

    Un modelo para priorizar las capacidad digitales necesarias para navegar en la incertidumbre

  • Decoder

    Una guía tecnológica de la A a la Z para líderes de negocio

  • Todos los Insights

  • Artículos

    Opiniones profesionales que ayudarán al crecimiento de tu negocio

  • Blogs

    Opiniones personales de ThoughtWorkers de todo del mundo

  • Libros

    Navega a través de nuestra extensa biblioteca

  • Podcasts

    Emocionantes charlas sobre las últimas tendencias en negocios y tecnología

  • Regresar
  • Cerrar   ✕
  • Visión general
  • Proceso de Aplicación

    Descubre lo que te espera durante nuestro proceso de selección

  • Graduados y cambio de carreras

    Empieza tu carrera en tecnología con el pie derecho

  • Ofertas de trabajo

    Encuentra puestos vacantes en tu región

  • Mantente conectado

    Suscríbete a nuestro boletín mensual

  • Regresar
  • Cerrar   ✕
  • Visión general
  • Conferencias y eventos
  • Diversidad e Inclusión
  • Noticias
  • Código abierto
  • Nuestros líderes
  • Cambio Social
Blogs
Selecciona un tema
Ver todos los temasCerrar
Tecnología 
Gestión de Proyectos Agiles La Nube Entrega Continua Ciencia e Ingenieria de Datos Defendiendo el Internet Libre Arquitectura Evolutiva Experiencia de Usuario IoT  Lenguajes, Herramientas y Frameworks Modernización de sistemas heredados Machine Learning & Artificial Intelligence Microservicios Plataformas Seguridad Pruebas de Software Estrategia Digital 
Negocio 
Servicios Financieros Salud Global Innovación Ventas  Transformación 
Carreras 
Hacks Para Tu Carrera Diversidad e Inclusión Cambio Social 
Blogs

Temas

Elegir tema
  • Tecnología
    Tecnología
  • Tecnología Visión General
  • Gestión de Proyectos Agiles
  • La Nube
  • Entrega Continua
  • Ciencia e Ingenieria de Datos
  • Defendiendo el Internet Libre
  • Arquitectura Evolutiva
  • Experiencia de Usuario
  • IoT
  • Lenguajes, Herramientas y Frameworks
  • Modernización de sistemas heredados
  • Machine Learning & Artificial Intelligence
  • Microservicios
  • Plataformas
  • Seguridad
  • Pruebas de Software
  • Estrategia Digital
  • Negocio
    Negocio
  • Negocio Visión General
  • Servicios Financieros
  • Salud Global
  • Innovación
  • Ventas
  • Transformación
  • Carreras
    Carreras
  • Carreras Visión General
  • Hacks Para Tu Carrera
  • Diversidad e Inclusión
  • Cambio Social
Gestión de Proyectos AgilesTecnología

The analysts' guide to APIs

Aaron Tushabe Aaron Tushabe
Paula Paul Paula Paul

Published: Oct 20, 2017

Almost every business or technical analyst today understand the benefits of exposing business capabilities through APIs. But how can you best achieve this?

It’s easy to get pulled into a technology-first view of APIs. After all, an API is an application programming interface — it just sounds very technical. As a business analyst, this might be confusing — even intimidating — especially when faced with the myriad of non-functional requirements (NFRs) documented in REST style guides, error codes, versioning, and use of HTTP headers.

Before you find yourself hurtling down that particular rabbit hole, take a breath and ask yourself a simple question: Where is the user in all of this?

In this article, we’ll explore the benefits of considering user stories when building APIs.

Putting the user front and center

Whenever we think of building APIs, we recommend coming back to the reason we need applications to talk to each other in the first place. An API is usually created because of the needs of the business and users. Generally, these APIs fall into two categories:
  • Private APIs. These enable businesses to ‘wrap’ or integrate with aging technology that they may eventually replace; to future-proof new front-end development or new capabilities that depend on existing technology.
  • Public APIs. These enable businesses to expose their capabilities to other businesses or consumers. For example, an API that allows external re-sellers to search for products or place orders for products through a programmatic interface. One example in this category is Best Buy.

We can look at the user stories through a different lens for these two categories. But both provide useful mechanisms that help companies on the path to adopting an ‘API as a product’ approach.

Private API stories

When it comes to private API initiatives, it can be tempting to simply focus on ‘just wrapping the existing system’. Beware: this can lead to a technology-first view of the API stories, one based on the technical design of the existing system. When the existing system is a monolith or has limitations — which is likely to be the reason the organization is pursuing a wrapper — you need to be sure that the stories reflect the desired business capabilities and not the existing technology.

Let’s take an example:
  • Start with a narrative to express the need
    Do you see stories in the backlog that take this approach? For instance: ‘As a developer, I need an API to fetch a list of products’. Here’s how we could re-write this: ‘As a developer, I need the products available for purchase so that I can show them to our customers via our website or mobile app.

    The tasks for this story, or breakdown of the feature, would need to address: security; the number of data fields needed just to display the order screen (as opposed to having an API that returns all the possible fields associated with a product); and some core API functional approaches for things like paging and sorting.

     
  • It’s not about just ‘slinging data’.
    Sometimes the ‘fetch the list of products’ story focuses too much on all the data that is associated with a product. That could involve hundreds of data elements, and filtering the information based on the customer’s status. You can simplify things by embracing the principles of YAGNI, and remembering that APIs will evolve over time. Where possible, you should avoid pursuing an exhaustive interface to represent the entire structure and capability of the existing system. Keep the Tolerant Reader Pattern (TRP) in mind, since consumers of a REST API can and should adopt TRP, and REST APIs can be expanded in non-breaking ways as consuming application needs evolve.

    If the API is intended to expose business capability from an existing system, ensure that the only the information that is needed to support the business case is exposed.
    You can apply the Tolerant Reader Pattern to API design; if the existing system manages 200 data elements and 20 behaviors or events for a core business entity such as ‘Product’, then: “Design the client or service [or API] to extract only what is needed, ignore unknown content, and expect variant data structures.”

    YAGNI and Tolerant Reader concepts can direct the API stories to real-world usage, not the underlying physical schema or all available data managed in existing systems.  

Interlude: memories of COM

Back in the day, COM programmers (“Each interface is an immutable contract of a functional group of methods”) had to agonize over interface design. COM interfaces were a way to create an API, just like REST. But, REST frees us from immutability — and we can move more quickly to create APIs that align with user stories, are tied to business capabilities, and are less concerned with existing data structures or schema. In some sense, for private API stories, the ‘Backend For Frontend’ (BFF) might be considered the ‘real’ API, with the fulfillment of the BFF via facades and adapters viewed as the concern of engineering. It’s worth considering that a business Analyst’s efforts could focus more on BFF when dealing with private API stories, and have facades/adapters and BFF fulfillment falls into the category of NFRs, or potentially ‘API as a Product’ concerns.

Public API stories

When your organization decides to expose a public API to enable communication with consumers or other businesses, you have to understand the underlying business needs and motivations.

Successful public APIs have clearly defined themes and are often branded. For example, the Best Buy API has clear messaging, defining the purpose of each API domain, and is written in such a way that a non-programmer can understand why Best Buy publishes these APIs. Amazon has a wide array of digital offerings, with APIs grouped by major service domain, and again, the intent is clear and understandable from a business perspective.   

Outside of the e-commerce world, we can see good examples of business-focused public APIs and branding from Lyft and Sabre; the completely API-driven business empire created by Twilio; and an evolving vision of APIs from Mercedes Benz. It’s instructive to look at the shapes and the core features of these APIs because they reflect the core business capabilities and visions of their companies.
 
This is why it’s important to have business analysts involved in both private and public API efforts.

What’s in your analysis tool box?

Domain Modeling and Event Storming are great tools for analysis, and for driving out API stories from a business and usage perspective. To avoid gumming up delivery efforts, we think it’s useful to define a reasonable scope for these exercises, and avoid complex ‘enterprise-wide’ modeling efforts.  

Event Storming is particularly useful if you get the sense that all the business capabilities are being forced into a REST API. REST in itself is not a complete solution: it’s just one tool that enables programmatic communication. REST lends itself very well to request-response needs (‘get products’, ‘post an order’). But with Event Storming, you can drive out needs for extending that communication to events and messages. For example, when an order is placed, who needs to be notified?  Business-truthful APIs consist of not only information and behaviors (often exposed via REST), but also events.  

The business-truthful concept goes back to the basics of object-oriented programming, as most business objects consist of properties and methods (which align nicely with REST), and events. Business-oriented analysis can provide the wake-up call when an API effort is getting conflated with ‘just build a REST interface around our existing systems’.

Using epics to track business value

One of the most commonly recommended approaches for breaking down work is through using service endpoints as story boundaries. However, with such an approach, you may run the risk of missing the user again — especially if the stories are endpoint-specific and not necessarily aligned with business value.  

A true business flow may require calling a series of several endpoints — say, customer creation, product selection, checkout, billing. Epics are a good way to track these business flows across several stories, which may be captured under different features or even different teams on larger programmes of work.

Once you’re tracking business flows with epics, they need to become your primary measure of velocity, as stories alone could give a false sense of progress. A common symptom of this is when your team’s burnup shows you’re delivering well but nothing seems to be ready to showcase to business stakeholders.

When you change your burnups to track completed epics, the result will help you appreciate the scope of the problem. Likely you’ll find that you have a lot of epics in progress and not getting to completion soon. Collaboration with your product owner to identify key business flows under epics and prioritize and limit the number of epics in progress.

The API is a product

At ThoughtWorks, we’re fans of the ‘API as a product’ technique — to the extent that it was moved in the ‘trial’ ring in our Technology Radar Vol. 16. private and public API efforts can be viewed through a product lens that extends the business motivations for the API. Using a product lens, we view the true customers of the API as software developers. That means developer experience, ‘time to hello world’ and technical consistency of structure and payload can be included as elements of experience design, in addition to developer needs for API discovery and documentation that enable effective use of the API.

There are ‘user stories’ to be written when viewing APIs through this lens, but the ‘API as a product’ technique does not exist independently of the original business need and motives for an API. As champions of these needs and motives, business analysts are responsible for keeping the team’s efforts focused on business capability and enabling ultimate user consumption of the APIs. This allows an adventurous and motivated business analyst to extend their skills to product management and more technical non-functional requirements management. All are necessary ingredients for a successful API strategy.

Pulling it all together: API strategy

Successful delivery of an API project relies on a combination of business-driven user stories, the appropriate API and Service Management Architecture, and an ‘API as a product’ considerations.

An API strategy is much more than ‘hide the complexity of my old systems behind a REST interface’. An API strategy ensures that:
  • High-value business capabilities are exposed digitally
  • APIs provide a delightful developer experience
  • APIs are true to the business versus existing technology or organizational structure (be sure to navigate the perils of Conway’s Law)

Crafting an effective API Strategy is outside the scope of this article, but effective user stories are a critical piece of the puzzle. Like all software, an API project is only meaningful if it is driven by true business needs, with the goal of delighting users.

In future posts, we’ll share more insights on API strategies, and adopting an ‘API as a product’ approach to exposing your business capabilities on a digital platform.

Technology Radar

Don't miss our opinionated guide to technology frontiers.

Subscribe
Blogs relacionados
Tecnología

REST API Design - Resource Modeling

Prakash Subramaniam
Aprende más
Entrega Continua

Continuous Delivery Cannot Succeed Without Business Analysts

Jenny Wong
Aprende más
Pune

Building Adaptive Mobile APIs with Legacy Services

Priyank Gupta
Aprende más
  • Nuestros Servicios
  • ¿Con quién trabajamos?
  • Insights
  • Carreras
  • Acerca de Nosotros
  • Contacto

WeChat

×
QR code to ThoughtWorks China WeChat subscription account

Relaciones con medios de comunicación y analistas | Política de Privacidad | Modern Slavery statement ThoughtWorks| Accesibilidad | © 2021 ThoughtWorks, Inc.