We need to remember that APIs exist to help complete a job-to-be-done. Either the job requires the use of the API to start and finish the work, it requires the API for some portion of the work, or the job is to bridge systems and organizations through machine-to-machine communication.

So, how do your API endpoints participate in these jobs? Even better, how do you explain the capabilities of your API endpoints to those less familiar with the technical details of HTTP, GET, and POST? It is time to start communicating about our APIs in a new way. One that supports the human side of APIs. It is time to start talking about our API endpoints as skills.

What skills do your APIs offer?

If I were to look at your API documentation – from your reference documentation in Swagger (now OpenAPI) to your getting started guides – what would I see? Would I see a bunch of content centered around your POSTs, GETs, PUTs, and DELETEs? Or, would I see the skills your API offers to get stuff done?

The worst offenders I have seen are API reference docs that like this:

GET /organizations
Description: Get all organizations

No kidding? The GET /organizations endpoint gets a list of all organizations?! Why do we allow ourselves to document our APIs this way? Instead of “Get all organizations”, we need to look for a better ways to communicate and share our API’s skills with our product team, our company, and our developer ecosystem.

Meeting people where they are

What skills do your APIs offer? Not the GET vs. POST. Not even hypermedia, though I find that aspect interesting for some API use cases. What does it offer to everyone involved?

For us to answer that, we must meet people where they are. What is interesting is that this isn’t the first time this theme has emerged in my life. For about five years, I wrote and coached individuals on volunteer management. While the topic was related to churches, many of the principles translated to the non-profit sector in general.

I was always asked about how to recruit volunteers, keep them engaged, and ensure that they had a place to land once their season of involvement with the organization was done. My advice generally came down to the following: you need to meet them where they are at, examine the unique skills they bring, and find ways to help them make a difference. Everyone is designed differently. You, as the leader, are required to adapt to their gifts and passions. Not the other way around. Otherwise, volunteers will leave and never come back.

For our APIs to be successful, we have to speak in terms that everyone on the team will understand. Help them realize their passions and what they want to do. You must adapt to the audience, not the other way around. And your documentation needs to reflect that as well.

Finding new ways to communicate our API’s skills

At this stage of my career, I’m an API consultant. I love helping teams understand how to align their business, product, and technology choices. My consulting focus is to help teams to think in APIs. I spend a considerable portion of the time teaching teams how to model and design APIs. I see myself as a product architect, helping teams to find what they do best (their capabilities), and find ways to build an API strategy around those capabilities.

Keith and I captured many of these steps in our book, “A Practical Approach to API Design”. In the book and during our hands-on workshops, we teach teams how to break down the jobs-to-be-done into steps. We then map those steps into API endpoints. The result is the beginnings of your API design, documentation, and vocabulary for how your API skills will be used – all centered around the skills of your API.

What we seem to lack is an easy way to map these endpoints and skills into the documentation, typically Swagger. ALPs may be a solution to this approach as it separates the semantics from the API design. I hope to explore more about this soon.

For now, I am recommending that teams adjust their way of communicating by focusing on API skills first. Begin to orient your discussions around them, so that everyone on the team can participate and understand the conversation at hand. Allow your project managers to understand the impact of a new endpoint by discussing the new skill or capability that it brings to the business. Next, integrate the skills into your documentation to provide better clarity and spark conversations outside of HTTP design details.

Kin Lane has been taking this approach with his university API workshop. He mapped out some Zapier triggers based on the skills or jobs that they perform:

Jeff Barr recently posted this tweet of how the AWS API is being used from Alexa to enable VoiceOps:

VoiceOps is here – “Alexa what’s the instance count?” https://t.co/0ZRnyQijyg pic.twitter.com/AcJUcKWp1v

— Jeff Barr (@jeffbarr) March 21, 2016

The interesting thing here is the mapping between the job-to-be-done, the AWS API, and Alexa’s Skills Kit (ASK) that enables it all to work together. I hope to write more about this soon.

Educating everyone on your API’s skills

Call them skills. Call them activities. Call them capabilities. But let’s stop discussing our APIs in terms of endpoints made up of URLs and verbs. Instead, let’s start talking in terms of API skills and mention those URLs and verbs only when we need to be specific about the technical details. When we do this, we can start to educate everyone on the team about how APIs work, why improvements are necessary, and the reason why the product and business should care. Your product team and customers will appreciate it.

Thanks to Kin Lane and Lorinda Brandon for the additional inspiration on this article.

Photo credit: Skills – Graffiti doodle by DeaDerV23

The post What Skills Do Your APIs Offer? appeared first on LaunchAny.

Chat: Not just for humans

The previous generation of messaging platforms offered very little in terms of integration solutions. Many focused on connecting humans, but didn’t extend the platform to allow for automation and integration.

The recent generation of messaging platforms, from HipChat to Slack, expanded their definition of messaging and collaboration to include software outside of the platform. Combined with the abundance of open, web-based APIs, these platforms have taken on a life outside of their original design.

These new products demonstrate what happens when you release the choke hold of a closed software system and embrace the true definition of a software platform. By allowing it to be extended through API integrations for emitting and receiving messages, businesses can change the way they collaborate. Entire business workflows can be viewed and coordinated inside of the messaging platform. And chatbots are leading the way.

Chatbots as a User Interface

Chatbots, or bots for short, are agents that can interact with humans to perform a task. The interactions may be simple and follow a pattern-based approach, such as ‘Add milk to the shopping list’. Or, it may be more sophisticated and able to understand human speech and interact in a conversation.

Bots are nothing new. In fact, they have been around for quite some time and used in different settings. The explosion of chatbots is due to several reasons:

1. The rise of messaging platforms, such as Slack and Hipchat
2. The growth of web-based APIs used for mobile and partner integration
3. Recent advances in AI, including natural language processing (NLP) and cognitive computing
4. Application fatigue from the overwhelming number of applications required to keep teams in sync and get jobs done
5. The growth of mobile devices that extend the reach of applications beyond the desktop

Messaging, combined with the power of APIs and chatbots, are changing the way we interact with software. This iteraction is becoming more reactive, contextual, and automated. To fully understand where this is heading, let’s first revisit where we are today.

Software Silos

The traditional view of software applications is that they are built to solve one or more problems that is either common across all kinds of businesses (i.e. horizontal) or for a specific kind of business or process (i.e. vertical).

When we need to look something up, we start the application and perform a search. When we need to enter data or perform a task, we go to the application to get something done.

The changing landscape of the user interface

Over the last 30 years, the user interface has changed – both in how we interact with it and where the interaction occurs. We started in the batch world, where humans had to share the hardware. Hardware became smaller and available for personal use, resulting in command-line and graphical interfaces.

Most recently, mobile devices have gained significant market share. No longer do we have to sit as a computer. The computer now comes with us, and can integrate context, such as location, into application usage. However, we have continued to live in a world of the graphical interface, although applications have become more distributed.

Over time, the user interface has become more disconnected from the source of data, requiring a dependence on the network to do our job. We have seen a huge rise in APIs that are correlated to the rise in mobile computing. This is a result of the user interface moving away from the source of the data.

Same APIs, different devices

What hasn’t happened yet is a change in the way we view applications. We still go to an application that is built to solve problems for a variety of use cases, contexts, and people. The application is still pretty generic, all things considered. Designers are required to find ways to ensure that the user interface can accommodate the most number of people possible while remaining useful for the experts – no easy task. This is starting to change, however.

We are now seeing the desire for different interfaces that build upon our network and API-driven world: device-based IoT, voice-command (e.g. Alexa), messaging (Slack with a command-line integration), and agent-based that combines NLP + voice/chat (e.g. Siri, Google Now, and Alexa).

This is breaking the tradition of application interfaces, no longer requiring users to go to a web or mobile interface. Instead, these interfaces are allowing application capabilities to go to where the users are active. And APIs are making it happen.

Enter: Slack

Slack has become one of the most popular ways of doing this, likely due to its considerable growth as a team messaging platform. This chart from Business Insider demonstrates their amazing growth:

Slack’s daily active user growth (via BusinessInsider)

While Slack is being used to connect tribes across business boundaries, it is primarily used for  more effective team communication. Separate channels are used by product teams, marketing and sales, and development to collaborate without interrupting others. These channels may be occupied by employees as well as contractors and vendors to expedite communications outside of the organization.

Chatbots: From Communications to Integrations

Slash commands bridge the gap between humans and APIs, sending the required data and displaying the response (e.g. obtaining current weather conditions by postal code). Some APIs may require a token or API key to prevent abuse of their service, but often that requires a simple one-time setup. Other slash commands may require an account on an existing application (e.g. a hosted Jira account) for the API to integrate properly with Slack.

Slash commands have a specific format or syntax and are best for specific API integrations, often transactional in nature. In the example above, we are using the built-in slash command for adding a reminder. Slash commands don’t monitor conversations, they simply respond to the given command, validate the input, and take action if the request could be processed.

Slackbots are then used to extend the capabilities of Slack by becoming part of a conversation or discussion channel within Slack. Rather than slash commands, they can listen for specific words or patterns and then participate in the conversation. Where slash commands are proactive and require direct interaction by a human, slackbots often are more reactive by responding to the conversation as it occurs. Below is an example interaction from Blockspring’s Weather Slack Bot:

Notice that there isn’t a slash command required. Instead, the bot monitors the channel for specific keywords and then attempts to interact with an individual or a channel based on what it sees. This is a simple example, but it demonstrates what is becoming possible. Things like Slackbots are starting to transform the way we interact with software and conduct business. We are now seeing application interaction move closer to where the humans are solving problems.

Where humans and APIs meet: the job-to-be-done

It bears repeating: We are now seeing the early stages of a transition from users going to the application, to applications going to the user. This is a result of the convergence of several things: Internet-connected devices such as Amazon Echo, conversation platforms such as Slack, and the APIs that extend their capabilities and connect them to external systems. Together, they are allowing user interfaces to meet people where they are getting things done, rather than forcing users to go to the applications to solve their problems.

Applications are most relevant when they meet humans to create and enhance the job-to-be-done. APIs are what make this possible. Applications are only relevant to the job they solve. Today, we see this primarily as a web or mobile application solution. Perhaps it is a device that captures data and summarizes it via a web or mobile application (where the mobile application might even run on a smart watch or other connected device).

With the introduction of platforms such as Slack for team messaging, combined with API-based integration for bots and voice interfaces that support command and natural language, things are dramatically changing. We are starting to see the focus shift from building applications to building capabilities via APIs and connecting them to any number of other applications and devices.

APIs deliver capabilities and context

If applications are most relevant when they meet humans, then the traditional application boundaries become less important. This creates a fundamental shift in the way products are viewed and constructed within an organization. Steve Willmott, CEO of 3scale, expressed this best in a recent interview:

I always feel a little conflicted about the idea of the “API as a product”. On the one hand it feel like progress that the API gets serious product management type attention. On the other, it plays into what I think is a fallacy that the API is a “separate” thing from what the company does. I would say in fact that it is not the case that your API is a product, instead that “it is part of THE product”, and specifically part of the “most important products” your company delivers.

What are your most important products in your organization? They probably aren’t applications. The most important products in your organization are the business and technical capabilities your applications enable people to do that they previously couldn’t without considerable effort. These capabilities can be combined into a variety of applications and integrations based on need, resulting in a customized workflow to complete the job. Rather than viewing applications as a series of use cases and stories with points, applications become the intersection of your capabilities with the capabilities of others into a solution that best meets the needs of your customers.

Believe it or not, your applications are not important. The single most important aspect of your organization is the problem you solve better than anyone else. Applications can be copied. APIs will be duplicated. The understanding, expertise, and insight you provide is unique and valuable.

Your applications and APIs are just the delivery mechanism.

This is the most compelling reason to move toward microservices, as it extends the agility of an organization beyond application delivery. APIs will emerge from one or more microservices that offer business capabilities, that can then be combined into applications.

When we start to build applications with this mindset, our perception of applications will start to change. Applications stop becoming a single installable download. Applications as we view them will become the combination of devices, integrations, and bots that collaborate to produce the necessary user interface and experience to meet the need at hand or the job-to-be-done.

What do companies, product teams, and developers need to do to prepare?

This is the real opportunity for digital transformation in today’s business, not just “going paperless” or building a few partner APIs. Companies that start to view their business and technical capabilities as part of this new wave of applications, made up of bots, devices, and third-party platforms, stand the most to gain from their digital transformation.

So, what can businesses and product teams do to prepare themselves? Five key things:

1. Companies need to focus on capturing their core business and technical capabilities as services, exposed as internal and external APIs. We’ve seen this happening for over 10 years with Amazon, from both their ecommerce and cloud businesses. Now it is time for small and mid-size companies to see their capabilities and unfair advantages as assets as well. Companies must move beyond IT-oriented web services and into capabilities exposed as APIs.
2. Business leaders must begin a top-down API strategy to expose business and technical capabilities to internal teams, partners, and public developers. This was Twitter’s early strategy and it resulted in Twitter apps being built for a variety of mobile platforms and devices that they couldn’t reach with their limited resources. APIs have the capability to impact the business and product lines – beyond partner integration. However, it requires buy-in from the CEO-down to be the most effective.
3. Product teams must reorient their thinking around constructing solutions that are multipliers of their business and technical capabilities. This means thinking beyond applications and into platform and device integrations that meet customers where they are are facing their problems, from Slackbots to Alexa Skills and beyond.
4. Product teams should look for ways to extend the reach of their products through voice, bots, and other integrations. These new channels reach beyond traditional web or mobile applications, opening new opportunities for engaging with customers in a variety of situations.
5. Development teams must learn to construct solutions from capabilities again, either through microservices, lightweight SOA, or modular monoliths. It is time to get back to the “first make it work, then make it right, and, finally, make it fast” often attributed to Kent Beck. We have no problem with the first step, but often miss the last two, short-changing our product and business agility in the goal of going fast and being agile. Teams that are able to find the balance of knowing when to simply make it work and when to make it right and make it fast will have a distinct advantage.

Where is all of this leading us?

Over the long term, I believe that applications will become more situational. In the future, many of the applications we will use may only exist for a limited time, perhaps only for a few months, weeks, days, or even a few hours. Then we will dispose of them and replace them with something else that is more appropriate to our current set of jobs, workflows, or team collaboration needs. Given the right tooling, development teams would no longer bear the burden of developing situational applications, instead focusing their time and effort on services and solutions critical to the business.

Unfortunately, today applications cannot be discarded today without losing data. Alternatively, if APIs are the center of computing, applications become a personalized integration that combines capabilities to solve transient problems. The API owns the data and capabilities instead of the siloed applications. Product managers start to track customer and developer engagements rather than requested features on a backlog. Businesses are able to unbundle and rebundle their capabilities to innovate and engage customers in new and exciting ways. We will get there and in less time than you think – will your company be prepared, or left behind?

The post Slack, Chatbots, and Voice: At the Intersection of Humans and APIs appeared first on LaunchAny.

A microservice architecture provides the opportunity to create smaller, loosely coupled services that focus on doing a small number of tasks well. The benefits to developers include the ability to focus on a smaller codebase, more isolated deployments that can occur more often, and less overall impact to the codebase when updating or replacing microservices as requirements change. The business also benefits by having a more composable business for greater flexibility and agility as new market opportunities emerge.

Whether you choose to build a monolith, or start with a monolith on your way to microservices, the best of intentions could still lead to problems down the road. Let’s examine how this can happen and how to prevent these kinds of monolith problems.

What is so wrong about a monolithic architecture?

Monolithic applications are popular because they are the easiest to construct. All of the code exists within a single codebase. Therefore, the code interacts within the same process, removing the need for network latency and failures common with distributed architectures.

However, teams may experience difficulties with monolithic applications as the codebase grows. Problems such as loss of agility over time, features requiring longer development time, and a fragile codebase. This is what I have termed monolithic regret.

What causes monolithic regret?

The majority of teams experience monolithic regret as a result of a lack of clear software architecture and boundaries. This may be the result of limited time, lack of focus, or the heavy dependence on a web framework that doesn’t encourage proper cohesion and coupling.

Software is the most flexible when we have a strong cohesion and loose coupling. What does this mean?

Strong cohesion means that code related to the same functionality is grouped together. Code modules that have a strong cohesion promote reuse and prevents code changes from impacting many areas across an entire code base.

Loose coupling means that the dependency between modules is limited, preventing modules from knowing the internal details about how they are implemented. This is typically accomplished through clear public APIs for a module.

There are several popular web frameworks that make building a monolithic application easy – almost trivial. These frameworks commonly offer accelerated development, code generation, open source plugins/extensions, simplified deployment and the ability to scale out by adding more instances as required to support the current load. The problem is that they encourage poor software architecture unless carefully managed. Below is an example layout of the directory structure for a Ruby on Rails application:

The problem I have encountered is that the opinionated directory layout and associated boilerplate generators lend themselves to monolithic regret for more complex applications. These frameworks have enabled many developers to leave behind complex frameworks, sparking fun and innovation across a variety of technology and programming language communities. But it has also led to a loss of focus on strong cohesion and loose coupling in our solutions.

Can you get around these sorts of problems with these frameworks? Absolutely. The problem is that these frameworks don’t default to a modular approach. It requires an awareness of proper software design, but it isn’t built in by default. There is nothing wrong with this, as long as developers understand the tradeoffs. But for the most part, they either haven’t understood them or have chosen to ignore them for the lure of short-term development speed over long-term maintainability.

To be clear, I’m not picking on any of these frameworks or the decision for a monolithic architecture. There is a time and place for both. In fact, I agree with David Heinemeier Hansson (DDH):

“Run a small team, not a tech behemoth? Embrace the monolith and make it majestic. You Deserve It!”

However, I would encourage teams to be thoughtful about the micro-decisions that they make as their application grows. These small decisions can add up to one big monolithic regret over time.

So, how can we avoid monolithic regret? By applying systems design to the development process to help us identify our module boundaries.

Designing a modular monolith

No matter the architectural style you choose, my recommendation for every product company and enterprise I advise is to focus on modularizing their applications. By breaking applications into modules, teams can better minimize the low cohesion that results in fragile codebases and slower development. It will also begin the preparation for a move toward a microservice architecture as your organization grows.

To understand how to modularize our monolith, we must apply systems design techniques. For those not familiar, or perhaps a little rusty, here is a quick review the core concepts of systems design:

Systems design is the process we use to identify and capture an application’s structure, behavior, and infrastructure. It involves decomposing the application into:

Systems: This is a completely independent system that provides a solution to one or more problems

Subsystems: Bounded concerns that help to compose the system itself. Subsystems do not offer a solution on their own, but contribute a bounded portion of it.

Modules: These are the building blocks for composing subsystems. Modules may contain one or more components, where components are classes in object-oriented programming languages or functions in functional programming languages.

Notice that you can also have subsystems that are decomposed into other subsystems. This is often the case in more complex solutions. Through the application of system design, we can determine the boundaries of our system and how we want those boundaries to interact.

How to find subsystem boundaries

One of the more difficult steps in applying systems design to software is finding the subsystem boundaries. If the boundaries are drawn incorrectly, it can lead to tight coupling between each subsystem and its modules.

My preferred approach is to first model the workflow that the application must support. This involves breaking down the requirements into the activities and steps necessary to accomplish the goals or tasks at hand. Those that have read the API design book I wrote with Keith Casey will recognize this approach.

By identifying these activities and steps performed by each participant, also known as an actor, we start to see a picture of how these steps are related:

Once the activities and steps are visualized, you can then start to find the boundaries where different participants are involved. Areas where only one particular party performs related steps form the subsystem boundaries:

Each subsystem should then have a well-defined, well-designed API to allow the application to perform the associated activities:

Whether you plan to implement your API within a single codebase as a monolith, or eventually decompose your APIs into microservices, this technique will help your subsystems and modules to be highly cohesive internally and loosely coupled between each other.

A word of caution about module dependencies and the DRY principle

If you plan on migrating to microservices, then the DRY principle must be used with caution. Dependencies on other modules will make it difficult to later migrate to microservices. Strive to be DRY within your modules and be willing to duplicate behavior across modules for easier migration to microservices in the future.

Moving toward microservices

Choosing to take a monolithic approach to your application architecture doesn’t have to end up in monolithic regret. By applying the proper design work as new features are implemented, your team can better modularize the application codebase. The result will be a more maintainable codebase and a team prepared for migrating to microservices in the future.

Want to learn more? Check out the slide deck below from my talk at the 2015 API Strategy and Practice Conference on designing long-lasting web APIs, where I covered these topics in more detail:

If you prefer to watch the talk instead, you can view it below:

The post Avoiding Monolithic Regret appeared first on LaunchAny.

So, how can we resolve these conflicts so that both parties have their goals met? Let’s look at three examples of common API design frontend/backend conflicts, then look for a way to resolve them.

Example conflict #1: Response payload formatting

Frontend developers often require the response payload to meet a specific structure to match the screen design. While it would seem straight forward to address the payload formatting requirements in the backend API, several situations may arise:

• The frontend visualization requires data aggregated in a specific way to reduce the coding effort required to build screen
• Teams are migrating existing screens to a new, API-centric architecture and don’t want to rework 10s to 100s of screens to match the new payload format

Watching teams argue about response payload formats is painful. Backend developers want to implement plain JSON, JSON API, HAL, Siren, Hydra, or other formats with the goal of longevity and interoperability. Frontend developers often want formats that make it easier to marshal/unmarshal the payloads for easy rendering. I have been asked to be the tie-breaker in these sorts of conflicts. The difficulty is that no one team is right or wrong – they both have needs that are equally important.

Hypermedia-driven payloads are especially interesting as the backend API may be designed for mobile consumption through the embedding of related resource summaries. This can lead to a secondary issue of the n+1 query problem as clients are forced to navigate hypermedia links for related resources. Let’s examine this conflict next.

Example conflict #2: Performance problems due to n+1 API calls

You have probably experienced database performance problems from n+1 queries before. The n+1 query problem occurs when applications perform an initial database query, then perform a new database query for each result of the first query. For a query that results in 100 results, the application makes 101 database calls. That is not the most performant way to build a web application.

While the database n+1 query can impact our web application performance by a few hundred milliseconds or so, the impact on APIs is considerably higher due to the addition of network latency. Additionally, there is often considerable work for the API consumer to write the client code to fetch the initial API response, then perform tens to hundreds of follow-up API calls to fetch the additional data and build the necessary data structures to drive a single web or mobile screen.

Key indicators that n+1 API calls is an issue:

• The target device has limited network bandwidth and requires additional data to be available that isn’t supplied by the backend API
• Developers designed response payloads without summary details for related resources, forcing the API client consumer to resolve the issue themselves

Unlike example #1 above, the impact of this issue is not limited to what the frontend developer. Instead, performance issues can be exposed to the customer, resulting in a poor user experience and customer churn.

Example conflict #3: Database-centric API design

When teams say that they are using REST for their API, it can pretty much mean anything. From RPC-style APIs, to those building hypermedia REST and everything in between – API designs can have a variety of different approaches.

One popular approach is to wrap your database with an API. I don’t recommend this approach, as web-based resources often need to represent a more course-grained view of your system and include workflow affordances for the client.

However, there are times when taking this approach just makes sense or is necessary to meet particular business need. I wrote an article about this some time ago, where I outlined the steps to take if you really need to take this approach – including how to design a better API in the process. However, a straight CRUD-over-database approach does bring its own kind of conflicts:

• Tight-coupling to database schema, resulting in a change to the API payload field names when a column is renamed or removed
• Lack of higher-level workflow endpoints, forcing multiple API calls to be made to accomplish a goal (similiar to the n+1 issue above)

From my experience, this seems to be the most common as APIs are often designed bottom-up from an existing database. Frontend teams must then struggle to map a solution-centric user interface to a storage-centric API design. However, backend developers tend to be unwilling or unable to make the appropriate changes to optimize the API calls required to accomplish the task at hand.

Conflict resolution through layered API design

The hope is that our integration between API clients and server will look like the following:

As you may have noticed, this isn’t always the case. Instead, a few issues may arise that are at the root of this conflict:

• The frontend team want to reduce the burden of coding by requiring that payloads fit the UI design and limit API calls where appropriate
• Backend developers want to optimize the endpoints for both reuse and rapid development

To resolve this conflict, we need to find a way to support both parties. A common approach to doing this is by using layered API design. Within the microservices space, this is commonly known as the Backend For Frontend (BFF) pattern.

The BFF pattern allows the backend API to remain as-is, with a new API constructed and consumed by frontend developers to meet the needs of the UI. There are two primary approaches to use the BFF pattern:

The Application-centered Approach:

• Driven by use cases by the end user, often workflow related
• Traditional backend APIs are viewed as smaller composable endpoints
• Use cases are realized by combining these smaller composable endpoints into new APIs
• This is similar to traditional SOA or microservices

The Device-centered Approach:

• Driven by the device functionality (e.g. mobile app, web)
• Encourages the repeating of code across device APIs, adapting payloads and even behavior as necessary
• Supports reducing roundtrips for mobile applications that have to handle unreliable networks

Both approaches support the idea of pushing the orchestration closer to the server tier where the backend APIs resides and network latency is lower. This reduces client network traffic to just one or two API calls to the BFF API, which can be significant for mobile applications.

Use caution applying the Backend For Frontend (BFF) pattern

The Backend For Frontend API design pattern is a useful tool for teams to resolve conflict and ensure that APIs solve real world problems. One major downside is that this creates yet another API that needs to be maintained over the life of the application. For larger organizations, this may not be an issue; however, smaller teams may struggle to keep up with the changes to the backend API and one or more frontend APIs.

Another hazard is that these layered APIs are not treated as well as the “flagship” platform API. At best, lapses in security, documentation, testing, and design will creep into these APIs, exposing the product to a variety of issues. Worst case, personally identifiable information (PII) may be released without proper authorization, or industry/government regulations may be compromised.

Don’t take shortcuts when building device or application-centered APIs to address these conflicts. Treat them as API products themselves.

The post Resolving the Frontend/Backend API Design Conflict appeared first on LaunchAny.

Lesson #1: Involve everyone, including product and business

APIs aren’t like many of the software development technologies that tend to be hidden away in the implementation details. Instead, they are an architectural concern that requires involvement from a variety of team members beyond developers. As a result, a variety of different team roles need to be included: developers, QA teams, technical writers, product managers, product marketing, and ScrumMasters.

While some may argue that any of these team members could attend a developer-centric API training program and learn something, there are often some critical pieces missing when we only focus on developers:

• QA teams are often left out of standard training curriculum, leaving teams uncertain about how and when to test web APIs
• Technical writers are left out and are therefore uncertain of what to document, when, and what tools exist
• Product managers miss opportunities to build better business value and increase organization agility using web APIs
• Product marketing may lack clear understanding about developer concerns around web APIs, creating missed marketing opportunities
• ScrumMasters are unable to integrate the varying processes for designing, developing, and deploying great APIs compared to standard product development

By building in each of these aspects into your API training program, each member of your product team will better understand and apply the fundamentals of web API design and development.

Lesson #2: Focus on a product-based approach to APIs

In the early stages of API adoption, most APIs solve a specific problem and often begin as a bolt-on solution within an existing application. As a result, the API design is specific to the application and difficult to reuse.

Taking a product-based design approach to APIs encourages teams to think beyond a specific application. The result is the company seeing APIs as first-class products rather than integration solutions.

We found that training teams to think in terms of products (external or internal), rather than integration points for applications, opens up teams for those “AHA!” moments that differentiate market leaders.

Lesson #3: Train for the full API development lifecycle

During our workshops, we looked for opportunities to discuss how the various job roles should be involved with API planning, design, development, testing, marketing, and management. This helps prepare product teams for addressing real world problems, including missing or ambiguous requirements that could result in a poorly designed API.

To accomplish this, we use exercises that are outside of the team’s domain, resulting in a more focused learning process outside of company politics and problems. For our 2-day workshops, we also conduct a variety of group exercises that simulate API design from requirements, screen mockups, and existing database designs to better prepare teams to design APIs from real world circumstances.

Lesson #4: Cover the API fundamentals

The most important step when conducting API training is to get everyone to the same definition of an API. This may seem like an unnecessary step, but it is essential to cover the web API basics. Too many assume everyone in a product team knows what an API is and how they work.

If a single member of your team doesn’t understand API fundamentals, it can hurt the entire team. If some of your team members misunderstand some of the concepts, it could cause miscommunication, delaying or fixing your API design and development efforts – negatively impacting the business.

Also included in our training is an introduction to how HTTP works. On average, 25% of a class has never seen an HTTP request/response. Without a foundation in basic HTTP, learning web APIs will be difficult at best. Once they have a solid foundation in the basics of HTTP, examples of APIs will be better understood.

Lesson #5: Focus heavily on API thinking

Many API training programs spend a considerable amount of time digging in to the technical details of API design. While we agree that a great API design is essential, we have found that API modeling prior to API design is critical to product-based API thinking.

API modeling is the process of capturing the activities, or jobs-to-be-done, that users and developers will expect from the API. Without this preparation, too much of the focus is on the “how” of the API (i.e. the resources, HTTP verbs, and response codes) and less on the “what” and “why” of the API.

By focusing on API modeling first, everyone on the team can discuss and contribute to the core business needs. Team-based API modeling, rather than just involving dev leads and architects, is important. It helps to create team ownership of the API, rather than just developer ownership and ensures that everyone from the team becomes a stakeholder from inception to production and beyond.

Lesson #6: Keep code out of training – at the start

Refrain from getting too detailed too quickly on the implementation details. This is especially the case when developers build training materials, as they often want to get to the “show me the code” phase quickly.

However, we have found success in teaching the fundamentals, business drivers, governance guidelines, and basics of API design to all team members first. By taking this approach, we help the entire team become more effective at solving problems alongside product and business goals prior to focusing on code.

This doesn’t mean that those in the workshop don’t interact with APIs. Instead, we use tools such as cURL and Postman to interact with APIs. We simply skip the coding step initially.

If a deeper dive is desired by developers, it can be covered in a follow-up workshop tailored for more technical team members. However, leaving programming languages and frameworks out of it prevent developers from adopting bad or default design patterns from frameworks while skipping proper API design-first techniques.

Lesson #7: Prepare the team for success and follow-up afterward

Try to allocate a full day to the training when possible, with the attendees considered “out of the office” and unavailable for email, phone, or instant messaging. This requires scheduling the training during a time when there will be no new product releases or other projects due.

If necessary, split teams into separate groups to prevent an entire team from being away on the same day. This may require training across multiple days, but will keep the training on the same week to encourage better understanding as more team members attend the workshop.

Our workshops cover a lot of material in a short period of time, often in 1-2 days. This means that questions will arise. We make ourselves available via email for follow-up questions, as well as provide a copy of the slide deck and our book to reinforce the concepts and provide a reference as teams begin their API journey.

The post Lessons From Training 1400+ People in Web API Design appeared first on LaunchAny.

1. We must first move beyond API reference documentation and look for other ways to communicate the value and purpose of your APIs

2. APIs are conversations between client and server. Extending these conversations is important and documentation can help surface opportunities and gaps in the conversation

3. As we write our API documentation, we need to ensure that it addresses the 10 questions developers and decision makers will ask before, during, and after API adoption

With this foundation, our next step is to define an overall API documentation strategy. This strategy will unify your API design and documentation, causing them to work together to produce a better developer experience. At the same time, it will address any questions key decision makers may have along the way.

An approach to API Documentation Strategy SUCCESS

To make it easier to remember, I have defined a simple acrostic as a simple way to help define a complete strategy: SUCCESS.

(S)olution-focused

Your API documentation strategy must first be solution-focused. If your API and related documentation does not help developers and users solve problems, then you will struggle to gain adoption.

A solution-focused strategy means consistently finding ways to:

Explain the benefits that your API provides. For example: saving time, reducing expenses, increasing revenue, and/or improving collaboration. To find your API’s benefits, ask how the lives of your developers and their customers/end users have improved as a result of your API. Your documentation’s role is to keep these benefits in mind and always challenge the API design when it doesn’t meet or exceed these expectations.

Once the benefits are clear, the documentation must guide developers on how to perform the various activities to be done to achieve these benefits. This is sometimes referred to as the jobs-to-be-done, which focuses on seeking to produce an outcome rather than focusing on the product itself. Once we understand the outcome, then we can support the necessary activities to get there.

(U)nified Understanding

There is nothing more frustrating then encountering an API that at first appears to solve a problem, only to realize that their product isn’t a fit because their definition of the problem or assumed domain concepts don’t match to your specific needs.

As technical writers, we must strive to be clear about the concepts our API supports (and doesn’t support). I encourage teams to define their domain concepts up-front. Otherwise, one person’s concept of a ‘project’ is another person’s concept of a ‘team’ or a ‘task’. Be clear, define everything up-front, and reference it consistently throughout your documentation.

On a side note, most web APIs expose resources that are named based on either the underlying domain model or database structures. When you surface these names without first defining your API’s conceptual model, confusion will likely occur. This may be the result of misunderstanding by developers, or something as simple as marketing terms creeping into the names of your resources, confusing developers on the meaning of resources. Be clear, define your concepts, and address areas that your API isn’t intended to solve.

(C)omprehensive

We covered this in a previous post, so I’ll simply summarize it here:

Provide an overview of the API, addressing concerns such as benefits, concepts, capabilities, and pricing of your API to qualify prospects. Also, make your API discoverable so that it can be found outside your website.

Case studies highlight applications that have been built using your API. Provide examples and reference applications to demonstrate some of your API’s capabilities.

Provide a reference documentation for each API endpoint to developers, including details on the URL, HTTP verb(s) supported, response codes, and data formats. Developers use this documentation when starting to consume API endpoints.

Guides offer help with learning an API, including its concepts and vocabulary during this critical stage. They also provide step-by-step guides for implementing common use cases.

Help pages and FAQs can guide new and experienced developers toward a better understanding of your API and proper usage patterns.

Create internal documentation to help your support team when developers get stuck. These assets may eventually become public documentation over time.

(C)ollaborative

APIs are, by their very nature, collaborative. Developers inside and outside of your organization are using something you have built and shared. This means that it is important to find ways to allow your documentation to include community ownership.

One way to accomplish this is by hosting your documentation on Github or other sites that allow for community improvement. We also suggest monitoring for posts and stories that document how someone used your API or struggled with your API, as these will provide greater insights into usage patterns and problems.

Finally, something that is often missed is promoting the products that are using your API. Share what others are doing with your API on your website by capturing case studies (with their permission, of course). This helps them to gain recognition for innovating on your API and helps website visitors know that your customers are experiencing successes with your API.

(E)ngaging

Many of us are familiar with API reference documentation tools, such as Swagger, that offer interactive documentation. This nice-to-have feature is quickly becoming a required feature in documentation today. Beyond this, however, lies a whole other opportunity for expanding your documentation to engage all types of audiences:

• Demos for interacting with your API to perform a task or see it in action
• Videos for demonstrating API capabilities and value to non-technical decision makers
• Tools such as Postman that allow for collections of API requests with sample payloads to be exported and shared with developers to accelerate learning
• Drip email campaigns, driven by the developer onboarding lifecycle and metrics, to teach developers how to use the API for better results or help them overcome problems

(S)trategic

While API documentation should be focused toward external problems, it can also help drive your internal strategy. This includes marketing and sales, which will better resonate if it aligns with your API concepts and solutions. API documentation can also drive search engine optimization (SEO) for organic growth.

API documentation may also drive key performance metrics, specifically customer acquisition costs (CAC) and customer lifetime value (LTV). A well-executed documentation strategy will decrease the customer acquisition costs (CAC), as it will require less sales and support staff to close and onboard the customer. It will also increase customer lifetime value (LTV), as you will be able to increase retention and reduce customer churn.

Don’t overlook your API documentation strategy when defining and tracking your API metrics. It can have a positive impact on your overall product strategy.

(S)ustainable

The final part of your API documentation strategy is sustainability. It is important to select the right tools that the team will use to keep the documentation fresh and up-to-date with the latest API changes.

Tool selection should match the technical skills available on the team. For example, if you have team members aren’t comfortable with Github, then you may have to invest time training them or select something else that is a better fit, such as WordPress. Whatever you select, it should have minimal friction to encourage updates from team members.

Sustainable documentation is important as code deliverables – perhaps more so, as without current documentation, no one will know how to best use your API.

The post Building Your API Documentation Strategy For SUCCESS appeared first on LaunchAny.

Your API Documentation Must Be Comprehensive

As previously discussed, our API documentation needs to move beyond API reference documentation and into all aspects of the API lifecycle. Unlike the typical SaaS-based product, however, your documentation has to target a variety of audiences, from the key decision makers to the developers ultimately integrating with it. There is no guarantee which type of audience member will encounter your API first, so your documentation effort needs to be comprehensive.

Your API Documentation Must Answer 10 Key Questions

To start your API documentation journey, it helps to focus on the questions that your audience members will ask. From the first time they encounter your API, to their initial ‘hello world app’ and beyond, the questions they will be asking are wide ranging. Being able to answer these questions will help your audience better understand what problems your API solves, engage with their first integration, and address their concerns as they consider formally adopting your API.

Question #1: Do you have an API?

Just because you live-and-breathe your API doesn’t mean others know you have one. Your corporate website and marketing materials are key entry points for those that may not know you offer an API. Be explicit about offering the API, as API-based products are still a new concept to many that will assume your product is a SaaS instead. Your documentation should call attention to your API offering, detail the problems it solves, and link to your developer portal.

Also, remember that if your developer portal is doing its job regarding search engine optimization (SEO), then non-developers may happen upon your developer portal as well. So, offer ways to get back to the overview for your product for those not as familiar with APIs. Or better yet, help them learn a little more about your product offerings and API at the same time.

Question #2: What can I do (and not do) with your API?

Once your audience begins to explore your API, they need to know what it does (and doesn’t do). Start with the problems your API aims to solve first, then move on to the features of your API that solve those problems.

By focusing on the problems and resulting solutions, you focus on the need rather than specific API endpoints. This is often accomplished through: getting started guides, integration/solution guides, and reference applications – all scattered with lots of easy-to-read code examples that can be used as a launching point once development begins.

No one will care about your beautifully designed API if they don’t know what kind of problems you can solve for them. Both decision makers and developers are trying to solve problems, not add more API integrations to their codebase. Find the problems, offer a solution, and then detail some of the nice features of your API to reinforce your API value.

Question #3: Does your API fit my company’s needs?

Once you establish the kinds of problems your API addresses, the next step is to make sure your API aligns with their specific needs and identity. Part of offering an API product is positioning your product so that it is seen as the right solution *for them*.

By offering use cases, case studies, and example applications, your product is easily aligned with the kinds of customer segments that you want to attract (and as a result you focus less on other segments). These documentation assets also builds trust as customers begin to see similar companies as themselves, causing them to picture themselves solving similar problems.

Question #4: How much does it cost?

Ultimately, price is going to become a factor. If they get this far, they have at least spent time vetting your API solution and now want to know if it will meet their budget. Be up-front with your pricing. Don’t hide your pricing behind a “Call us” link. This doesn’t mean that you can’t offer an enterprise license that requires a phone call, however.

At a minimum, provide enough pricing information to help them understand your pricing model (e.g. subscription, per transaction), subscription tiers (e.g. free, solo, team, enterprise), and what kind of support is available for each tier (e.g. forums, email, 48 hour phone, 24 hour phone, 4 hour phone). Being up-front with your pricing helps those conducting research and prevents them from removing you from their short list due to your more closed pricing approach.

Question #5: How does your API view my world?

Every API approaches a solution to a problem in a different way. The API carries with it a specific view of the world: what accounts mean, the kinds of workflows supported, and the type of data considered important.

As an example, let’s consider three popular project management APIs: Basecamp, Trello, and Rally. Each one has different views on how projects should be organized, how tasks should be created, and how they are marked as completed. Depending on how your organization prefers to manage projects will determine which solution is the best fit for you.

Therefore, it is important to document your API concepts, resources, data structures, and field types. Doing so will provide greater insight into how your API views the world and the solution to the problems your audience faces. While some view API reference documentation as the place to do that, I often recommend using Markdown or HTML-based introductory guides to capture concepts, common vocabulary, and high-level resource definitions. When sprinkled with anchor tags for deep linking, your API reference documentation can link to the specific concepts useful for the specific resource/endpoint being viewed.

Question #6: How do you secure your API?

Security of your API is important, particularly with the API security stories recently in the news. Too often, however, security is an afterthought when building APIs. Nearly every API will provide access to sensitive data, internal business systems, or share user data. Up-front security considerations prevent last-minute API design changes that make the API more difficult to use.

Your documentation should provide details on how your API handles authentication, authorization, and data security (both security in motion and security at rest). This will reenforce your product’s dedication to a professional, production quality service that will stand out against competitors.

Question #7: How long will it take to get started?

While many modern web APIs offer self-service onboarding, not every API does. If your API does offer self-service onboarding, call this out in your documentation as a benefit to getting started faster. For those that require time to go through a partnership program, include this in your documentation as well. This will ensure that the appropriate lead time is factored in prior to developers beginning the first ‘hello world’ integration.

It is also a good idea to point to example applications that have been built with a variety of programming languages, as a way to get started quickly. We recommend using Github or other public source code repository, so that developers can quickly clone your examples, configure their API key or OAuth token, and try out your API.

Question #8: Do you offer helper libraries/SDKs?

Not all developers want to code the HTTP client from scratch. This is particularly the case for developers that are new to web API integration, or for those that prefer to use their IDE and code completion to get their job done faster. If you offer SDKs, reference them in your documentation as well as in code examples. Stripe’s API documentation is a great example of integrating examples in multiple programming languages into their documentation.

Question #9: What API endpoints and event integrations does your API offer?

You will notice that we are nearing the end of our questions and only now getting to API reference documentation. Reference documentation is only one part of a complete API documentation strategy, even though it is an important one.

Your API reference documentation should list all of the available API endpoints, including details about data structures, success/error status codes returned, and request/response payload formats. Keep in mind that this reference documentation must be thorough and complete, as external developers will not have access to your source code, internal diagrams, or private documentation.

Remember that not all API integrations are one-way communication patterns. Find ways to offer a complete API conversation, allowing your API clients to make API requests when needed (“asking”) and be informed of specific server-side events (“telling”). Whether you decide to use Webhooks, Websockets, or SSE, find ways to extend your API design beyond the simple request/response design. Then, offer documentation about these integration options to show how developers can extend the typical integration scenarios with more robust options.

Question #10: Why am I getting this error code or unexpected response?

Once developers start to work with your API, they will likely encounter unexpected errors. Offer support docs with FAQs, troubleshooting guides, and developer support to help them overcome these issues and be successful. Documentation that consists of getting started guides only should be considered incomplete.

(Bonus) Question #11: What do I do if I’m not a programmer?

Not all visitors to your API product page will be developers. For those that aren’t, show them ways to use your APIs via tools such as Zapier/IFTTT, a third-party solutions marketplace, or an integration partners page. Even better, give them a demonstration of your API through a simple web or mobile app to spark their imagination and get them to take action.

The post 10 Questions Your API Documentation Must Answer appeared first on LaunchAny.

As API providers and designers, we can forget what it is like to consume APIs as we get so busy building them. So, let’s revisit our API design from the client view of the API conversation to see how we can make it even better.

How API clients see our API design today

APIs tell a story. Part of that story is the conversation that is exchanged between the API client and server. It often goes something like this:

The problem is that we often add in update and delete support, then stop the design effort. Our API is not much of a conversationalist, is it? We need to look for ways to extend the conversation our API clients can have with our API. Let’s examine a few ways we can do this.

Extending the API client conversation with hypermedia

One consideration may be to add hypermedia constraints to your API. This moves the focus from a content-only design to a context-centric design. Our API can now tell our client what is possible (and what isn’t) based on the current state of the system, perhaps combined with the caller’s permissions of what their role allows them to perform (sometimes called entitlements).

The conversation starts to get a lot more interesting when we add hypermedia. For example:

So, now our client is interacting with the server using a hypermedia API. It is able to better understand both the state and actions available, along with links to related resources. The client can now present its user interface, showing or hiding links and buttons as appropriate based on the hypermedia links present (or absent).

Another advantage of hypermedia is that it can prevent the need to push out new versions of the app to our app stores when minor changes to business logic are made on the server. Our application is now a little more resilient to changes in server-side logic and our client will immediately reflect those changes if behavior is driven from the hypermedia links. Perhaps the client is a universal client that knows how to talk to any kind of hypermedia API (we can dream, can we?).

Extending the API client conversation with concurrency control

But what about when something changes on the server side? How will we know and ensure that we are kept in sync?

A common solution to this problem is to add API support for ETags and the If-None-Match header, pushing the business rules that determine when a resource has changed to the server rather than the client.

For those not familiar, an ETag is an opaque identifer for a specific version of a resource at a specific URL. They are often, but not always, represented as one of the following: the hash of the resource state, the last modified timestamp, or a version number. An ETag is sent back to the client when a resource representation is sent to the client. The client may then use the ETag to perform actions on the resource, but only if the ETag matches (or doesn’t match if that is the desired behavior).

Now when we are retrieving a resource representation, the API client will receive an ETag as well:

The client can then ask to update a resource only if the resource hasn’t changed since it was last retrieved:

It also prevents overwriting resources that have changed underneath us by forcing our requests to match a specific resource ETag/version:

This will save our clients lots of problems and ensure our server-side state remains consistent.

Extending the API client conversation with cache support

Sometimes our clients need to know if a resource representation has changed on the server side to prevent displaying or working with stale data. Currently, our API design would require our client to retrieve the most recent representation every time, whether it has changed or not. The client is responsible for trying to figure out if the resource has changed by comparing it to a previously stored representation, or by completely replacing any previously stored version. However, the client doesn’t know the business rules that indicate a resource has changed (and shouldn’t have to know) . We need a way to allow the API server to inform the client if a resource has changed since it was last retrieved.

To achieve this, most API clients will occasionally check for resource changes using the ETag approach described above. The conversation may go something like this:

This kind of loop has to be executed for every resource you want to monitor, which may be in the hundreds of resources. That’s a lot of conversations and work for the API client.

Instead, some APIs may offer an optimized solution, providing a specific endpoint to poll and receive any changes across a resource collection:

Now our API client can be informed when one or more resource representations have changed and refresh its local data to reflect those changes.

You may be thinking that polling an API seems like a clunky approach to keep client data up-to-date – you would be correct. We can solve this design problem by adding support for server-originated conversations.

Extending the API client conversation with real-time API messaging

Real-time API messaging changes the conversation dynamic from one-way (client-initiated) to two-way. The client doesn’t have to be the initiating party in this conversation. Instead, the server can start the conversation when it becomes aware of an internal state change. This means that we can start to have conversations like the following:

Now, clients can respond to change by allowing servers to initiate communication. Whether you decide to use Webhooks or WebSockets, opening up your API to two-way communication enables the creation of collaborative API integrations.

Moving the API design discussion forward

Many of our API design discussions today are focused on applying proper HTTP principles. There is nothing wrong with this and it is an important step in the API design process. However, by focusing only on a data-centric request-response design style, we are missing a great opportunity.

Instead, we should strive to design our APIs to change the entire conversation that is taking place with our API clients. These new conversations afford clients the opportunity to fully collaborate in conversations between the server. This includes support for real-time API messaging to allow APIs to engage in rich conversations with our API clients.

The post Improving Your API Conversations with Hypermedia, ETags, and Real-Time APIs appeared first on LaunchAny.

While it is an important step to create API reference documentation, focusing only on these docs can cause you to miss the hidden value that API documentation can bring to your customers and your team.

The Hidden Value of API Documentation

API documentation tells the story of your API. From the getting started guide, to core concepts and examples, your API documentation informs the audience about how you see their problem. As we know, we can solve problems using a variety of approaches and points of view. Your documentation tells me your story: how you see the world, my problems, and your solution to those problems.

API documentation is the primary communication medium between API provider and consumer. Unless the API is open source, you will likely never see the source code behind it. Therefore, the only thing that developers consuming your API have is your documentation. Without clear and complete documentation, developers will struggle to use your API.

API documentation validates API design prior to implementation. By including documentation as part of the process and including technical writers during the design and development process, API design flaws can be spotted before coding has been completed – when changes can still be made easily and with minimal impact.

Beyond API Reference Documentation

We use the term “API documentation” as if there is only one kind of documentation. Yes, you need to deliver a great API reference for developers. Tools such as Swagger, RAML, and Blueprint are just a few of the formats available to help build them. However, complete API documentation requires more than just your API reference in HTML or PDF form. It requires looking at the marketing, development, and customer support aspects of documentation as well.

As you see, it takes more than just generating an API reference to fully document your API. Let’s examine each of the options available to help compose your complete set of API documentation:

Marketing-Focused API Documentation

Features and Discovery – Provides an overview of the API, addressing concerns such as benefits, capabilities, and pricing of your API to qualify prospects. This may include marketing content for developers and key decision makers, as well as automated discovery through formats such as APIs.json.

Case Studies and Examples – Case studies highlight applications that have been built using your API. It is also useful for sharing usage of your API by applications that have been internally deployed and therefore not generally not accessible. You may wish to consider providing examples and reference applications to demonstrate some of your API’s capabilities prior to developer sign-up.

Development-Focused API Documentation

Reference Docs – Provides a reference for each API endpoint to developers, including details on the URL, HTTP verb(s) supported, response codes, and data formats. Developers use this documentation when starting to consume API endpoints, whether for the first or the tenth time. While some developers may use reference documentation to become acquainted with the API product, it is most often used for exploration, development, and troubleshooting. This is where Swagger, RAML, and Blueprint formats are used to generate documentation from an API definition.

Guides and Concepts – As an API consumer, the most difficult part of using an API is the initial learning curve. Guides offer help with learning an API’s concepts and vocabulary during this critical stage. They also provide step-by-step guides for implementing common use cases. Combined with links to reference docs sprinkled throughout, developers are able to get started quickly and with confidence.

Support-Focused API Documentation

Problem/Resolution – Sometimes developers need a little help when consuming your API. Documentation that helps developers troubleshoot error response codes can ease the burden on your developers and support staff. In addition, help pages and FAQs can guide new and experienced developers toward a better understanding of your API and proper usage patterns.

Internal Docs – For those instances when developers need more assistance with your API, it is important to have internal assets to help your support team. Don’t forget to create and maintain internal design documentation, including diagrams and code comments, which go a long way to debug difficult issues.

Putting it all together

There are a variety of API documentation types beyond the typical reference documentation style we see today. Each one serves a different purpose to support the API both internally and externally. You will need to mix-and-match them depending on the purpose of your API to create a complete set of documentation. Be sure to select the ones that support your developers, your team, and the story your API tells.

The post Moving Beyond API Reference Documentation appeared first on LaunchAny.

However, many have not experienced Heroku before or have not considered it for an API deployment solution. This article provides an overview of Heroku, including how it works and how to get the most out of deploying your API to their platform.

What is Heroku?

Heroku is a Platform-as-a-Service (PaaS) that offers managed services for the deployment, management, and scaling of web applications. Acquired by Salesforce, Heroku has become an accepted platform for quickly deploying and scaling applications for startups and enterprises. There is no requirement to create custom deployment and server configuration scripts, as it is all handled by the Heroku platform, command line tools, and its integration with git.

Heroku is currently on the third version of their platform, codenamed “Cedar”. Originally focused their services around Ruby on Rails, the current Cedar stack is designed to handle technology stacks beyond Ruby and Rails. This provides flexibility for companies that may need more than one technology to build a solution.

A single Heroku account may host any number of applications. Each application has an owner and may have any number of collaborating accounts, allowing multiple members of a team to deploy and manage an application. Applications may be accessible via a standard HTTP connection or via HTTPS if an SSL certificate is installed.

How Does Heroku Work?

Heroku utilizes Amazon EC2 instances for deployments to their platform. This enables other Amazon-based services to be used in-network, reducing or eliminating most bandwidth charges.

The service is currently deployed to us-east-1 within AWS, limiting the ability to deploy to multiple regions. Deployment to multiple regions is currently being evaluated and is likely to emerge in the future.

Dynos are processes managed and monitored by the Cedar Stack, typically associated to an application tier (e.g. a web application) or service (e.g. background job processor). Dynos are contained within a Dyno Manifold that isolates the application, including libraries (e.g. Ruby gems), from other applications for security.

Dynos may be increased or decreased (to 0) as needed. The Heroku platform will perform the work of deploying the application to more or less dynos, as required. Heroku provides one dyno for free per application.

Managing Your Heroku Applications

Heroku management is based on a public API that is available to all accounts. This API may be used directly for custom integration into an internal release management workflow.

In addition, the Heroku CLI (“command-line interface”) allows for full access to the API in a scriptable manner. This includes the instantiation of new applications, management of add-ons, life-cycle control, remote monitoring, log file access, and remote process execution such as upgrade
scripts. The CLI is useful for developers that wish to manually interact and/or automate the management of their applications.

A web-based management dashboard is also available. It has been built on top of the management API with basic provisioning, configuration, and rudimentary statistics (disk usage, allocated dynos, etc). However, most find that the CLI or API is the best method of managing deployed  applications.

Why is Heroku such a great fit for deploying APIs?

There are several advantages for deploying your API to Heroku:

• Removes the need to setup and configure servers and network infrastructure
• One-step to deploy your latest code, using the command-line, Github integration, or their new one-button deploy feature
• Security updates are managed by Heroku staff, not your staff
• Ecosystem of Heroku and third-party add-ons allow for easy extensibility
• You can scale your processes up or down as needed to meet demand, using their command-line, API, or web dashboard
• Background processes can easily be deployed and scaled for long-running jobs, message processing, and other computational needs
• Provides a platform for deploying solutions built using a microservice architecture

Taking Advantage of the Heroku Ecosystem

Heroku has a variety of add-ons that can be used to enhance and extend your API. These add-ons are services offered by Heroku or third-parties that may be provisioned for free or a monthly charge. Certain add-ons are free or have a free tier, but use caution when enabling add-ons to prevent unexpected charges on your monthly Heroku bill.

Settings such as user names, passwords, host names, and tokens are passed to the application using environment variables. Some add-ons, such as host name-based SSL, require additional configuration steps to be performed for the application before the add-on may be enabled.

Must-Have Add-ons

There are a variety of very useful Heroku Add-ons that can benefit APIs. The following is a short list of those we generally recommend for consideration. Of course, your specific API architecture and implementation requirements may vary, so be sure that these add-ons will work for your specific environment.

Buildpacks – Not really an add-on, but buildpacks are used to setup and configure a dyno for your application. Many pre-built buildpacks already exist, but you can fork one and customize it as needed to ensure you have everything you need.

Domains – Configure your API to respond to your custom domain name, rather than *.herokuapp.com. Follow the instructions to setup one or more entries using CNAMEs.

SSL – Heroku provides a unique subdomain for each application, with SSL support. If you are using your own domain, you will want to generate and upload your own SSL certificate so that you can serve your API over HTTPS

PG Backups – If you decide to use Heroku’s hosted PostgreSQL service, be sure to enable the PG Backups add-on. It is free and provides options for 1 week or 1 month retention. Just be aware that developer databases support manual backups only.

Monitoring – Once your API is deployed, you will want to be notified when performance degrades or errors are identified. Try New Relic or 3scale (Kin Lane wrote an excellent overview article on using Heroku + 3scale).

Logging Services – Unless you choose to use an add-on such as 3scale for logging your requests, or if you are deploying your API alongside a web application, you will want to monitor your application logs. Heroku provides built-in logging, but look for add-on services such as Papertrail  to archive them and make them searchable.

Continuous Deployment – There are multiple solutions for continuous deployment on Heroku, including Travis CI and Codeship (which can help with your Github integration as well)

For a complete list of add-ons currently available, visit the Heroku Add-Ons page.

Overcoming Heroku Process Reaping

Heroku hosts of variety of applications, some of which see little or no activity during a 24 hour period. Therefore, Heroku has a policy to reap  processes after a period of no activity. These processes will be started once the Heroku routing layer detects an incoming request for an idle application. Depending on the start-up time required for your application, you may witness delays from a few seconds up to 30 seconds before the process is ready. This can be an issue for APIs that do not see consistent traffic but wish to offer consistent response times without this delay.

To overcome this, install the New Relic add-on or use a third-party website health check service. This will ensure that website health checks are sent to the site on a regular basis, ensuring that your process receives regular requests and stays active. Be sure to use a service that performs a check using HTTP or HTTPS, and that you have a static page or API endpoint that will return a 200 OK response code if your application is in a good state.

Securing Your API

There are several steps that we recommend be taken to secure your Heroku-deployed API. A few of these are specific to Heroku and its deployment model, while most of these are common to any application:

• The use of HTTPS for access to all deployed APIs either by using their pre-installed SSL certificates (for their *.herokuapp.com domains) or installing a custom SSL certificate (when using your own custom domain)
• Enforce secure database connections using SSL to protect sensitive data transmitted to and from applications (data in motion)
• Use of a strong passphrase for all Heroku and third party user accounts
• Ensure secure storage of SSH keys to prevent disclosure, replace keys if lost or disclosed
• Use individual contributor accounts rather than sharing a single user account to allow for easy revocation of API access when necessary
• Prevent sensitive data from being written to STDOUT or to log files, including submitted form field data by using a logging system with smart filtering enabled
• Passwords should be one-way encrypted and include a salt to further encrypt the password

Additional Resources

• Heroku Dev Center is full of cookbooks and HOWTOs
• Higher Order Heroku is a website dedicated to tips and links to articles, both from Heroku and other websites
• Common Heroku questions already answered on StackOverflow
• My slide deck from a short presentation given in 2013 to a local meetup:

Questions? Drop me a comment below or a private note and let me know.

The post How To Successfully Deploy Your Web or Mobile API to Heroku appeared first on LaunchAny.