January 25th, 2013

Considerations for Private APIs

Written by
 

Considerations for Private APIsIn the past, we’ve talked about the nature of private APIs (those interfaces that are built primarily to serve an organization’s own projects rather than to fulfill the needs of others).  But what are the specific challenges and architectural decisions that need to be made when implementing a private API?

First and foremost, an API can’t be considered private if it is open for widespread public use, right?  A simple way of keeping an API private is to host the interface on a public network without explicitly advertising or documenting its existence.  This can work well initially but may lead to problems in the future. If your service is valuable enough that others want to get their hands on it, even an undocumented, unsupported, private API can easily end up becoming a depended-upon API for application developers, resulting in an outcry when the API publisher has the audacity to modify or retire its own service.

A better approach is to provide access control at run-time and restrict usage of your API to a few known parties. There are a great number of methods for protecting access to internal resources but the best ones are those that achieve a balance between ease of implementation and resistance to infiltration. Security at all costs can greatly increase the complexity of an interface and – in turn – the time required to complete the projects that depend on it. Instead, we need to implement access control that is practical. Thankfully, security protocols like SSL, HTTP Basic authentication and OAuth 2 are great for providing the basic level of access control needed to make it difficult for outsiders to use a private API. Bear in mind that there is much more to API security than simply validating identity but this is the minimum level needed to ensure a degree of privacy.

Although a private API’s developers are generally known to the publisher, the best private APIs utilize API portal components to provide self-service registrations and integration to their private developer communities. This can greatly reduce the friction involved in getting API integration-based projects started and reduce the overall project costs for B2B and mobile-based initiatives. In fact, many of the lessons of simplified design, documentation and administration learned from the public API world can be directly applied to private API management. While the ultimate goal may be different (driving efficient API usage for private APIs rather than far-reaching adoption of open APIs), the ways of getting there are largely the same.

A unique characteristic of private APIs is the need to manage groups of developers. Unlike the public API space, private API publishers will often define out of band contract terms before offering up a quick self-service integration mechanism for that team. This type of group-based role definition is particularly common in integration projects that occur between organizations and can stretch the limits of API portal software that has been built primarily for open API use. Ideally, an API portal should at least be capable of managing developers within groups, communities or organizational affiliations as part of the self-service registration process. Even better, the portal could  provide capabilities for managing whole communities as separate domains within the same infrastructure.

Designing a private API certainly requires a different perspective but the good news is that much of the knowledge around public API design can be directly applied to interfaces you want to keep secret. Of course, building the management and security capabilities required to expose the API to your trusted parties can be daunting but that is why a great API management portal and gateway combination can save the day.

 

December 19th, 2012

API Design Tutorial: Pagination

Layer 7 Pagination Tutorial

At the Layer 7 API Academy, we’ve had a few requests from API designers who are seeking strategies for handling large amounts of data in API responses.  Pagination is the most common method for addressing this scenario. Pagination, which is very common on the Web, allows API architects to conserve resources, improve response times and optimize the user experience. It’s a way of splitting up data into “pages” and is used in just about any API that returns collections of data.

I’ve released a short video tutorial titled Use Pagination in Web API Design to introduce the ins and outs of the interface. This video provides a crash course explaining pagination and outlining how to use it effectively in the design of Web APIs. I couldn’t fit all the implementation considerations I wanted in this six-minute tutorial, so watch out for a follow-up video on the subject.

December 10th, 2012

API Design Tutorial: The Interaction Model

API  Academy - The Interaction ModelAPI design can be daunting. With so many decisions to make and so many differing opinions available on interface design, it’s easy to feel frustrated by the process.  Even worse, it’s possible to follow bad advice and end up designing an API that developers hate using.

That’s why we at the API Academy stress the importance of making rational decisions rather than irrationally selecting design patterns based on emotion or trends.  We want you to choose your design elements rather than picking them from the latest set of formats or technologies that you’ve heard about.

And that’s why we’re working on a series of tutorial videos, as my colleague Mike Amundsen recently announced. The first of these videos, titled The API Interaction Model – An Introduction, provides an overview of  a design process that will help you consider your user’s perspective in order to make effective design choices later. The ideas I discuss in this video are rooted in user-centered design processes that have been very effective in the software and product design worlds.

If you’re currently designing an API, invest five minutes and watch the video.  It should be time well spent.

November 20th, 2012

Behind Closed Doors: The World of Private APIs

Private APIsAttend any Web API presentation and you are likely to see a graph like this one, demonstrating the growth of  publicly-available Web APIs. Speakers (including me) love using these graphs for good reason: they succinctly capture the explosive growth of APIs that has taken place over the last two years.

It’s a great story but it’s really only half the story. Web API experts regularly acknowledge the existence of a “private” or “closed” API market. In fact, many of us believe that if the number of private APIs in use could be cataloged it would dwarf the 7,000 or so APIs that are published on the ProgrammableWeb site.

As with many of the terms in the API world, there isn’t a concrete definition of  “private API”. In general, a private API has these characteristics:

  1. It provides a language-independent interface that is made available via Web protocols.
  2. It’s access is limited to a specific set of known developers or organizations.
  3. It is not marketed to the general public nor is its documentation made publicly available.

Further to this, we can divide private APIs into three major buckets:

  1. Internal APIs that exist within the organization’s borders (for example, SOAP-based interfaces within an internal Service Oriented Architecture).
  2. Business-to-business (B2B) APIs that enable organizations to integrate with external companies.
  3. Backend APIs that drive mobile, Web and device-based applications.

With this definition we can see that there are a great many integrations that must already exist. Enterprises have been building SOAP and B2B-based connectivity for years and have accumulated healthy inventories of private APIs.

In addition, the headlong rush towards the world of mobile is driving the creation of new externally-facing APIs to help corporations reach their customers. As I’ve talked about before, many organizations wish to retain control over the development of these applications and they can do this with private APIs.

If IT teams have been building these types of in-house connectivity solutions for so many years, there shouldn’t be much room left for innovation or improvement, right?

Not quite. Unlike those who build private APIs, public API designers are motivated by the need for their interfaces to be chosen out of the mass of APIs that are available to their prospective users.  This difference in motivation has created a massive impact on how public APIs are designed and managed. Architects responsible for private APIs have a great opportunity to learn from the public API world by adopting design strategies devised to drive adoption, in a controlled manner.

A good reason to take a developer-centered approach to private API design is the development cost associated with building applications that utilize the interface.  A well-designed private API can reduce the project costs for application development as well as for maintenance and upkeep of the integration.  Good design isn’t easy but it pays off – even when the audience is limited.

Many enterprises are implementing a “private for now and public later” API strategy.  It is a great idea but that doesn’t mean architects shouldn’t strive to incorporate great API design and a solid management solution.

In my next post, I’ll dive into private APIs in more detail and talk about some of the specific challenges that arise when building closed interfaces and how these challenges can be addressed with management solutions.

November 2nd, 2012

Opening up Enterprise APIs

Written by
 

Enterprise APIsA few months back, I wrote a blog post titled “Are Open APIs Too Open for Big Business?” That post was about the challenges large businesses face when adopting an open API mentality. In it, I described the fears of brand damage and lack of control that prevent enterprises from opening up their data stores and services to the world. I also reasoned that large organizations could provide a new type of stable, trusted and highly-available API in the marketplace. Not a lot has changed over the last three months – big businesses are still absorbing the idea of open APIs and are continuing to weigh accessibility against control before taking the plunge. As before, the good news is that their reservations around control are being addressed with solutions like Layer 7′s API Management Suite, which lets them create a developer experience that will bring in the hordes while still keeping the gates secure.

The reality is that many enterprises are already taking advantage of the API wave by using open API tools and philosophies to create and mange private APIs that, in turn, power their branded mobile and browser applications. This is a good thing as it allows businesses to reach their customers and to integrate easily with smaller mobile and device development shops. Plus, it fits well with a corporate culture of control. But organizations are missing a trick if they don’t consciously explore the benefits of opening these APIs up and joining the world of platforms, developers and communities that rely on open APIs to power their applications and projects.

These are big decisions with big consequences. The success of an enterprise open API program will likely be dependent on those at the very top of the organization providing the necessary leadership and investment required for big change to happen. That takes time. In the meantime, the projects won’t stop, the need for B2B integration will continue and the consumer demand for applications on every device will grow louder and louder. In this climate, there is an immediate need for enterprises to release APIs (be they private or public) as quickly and efficiently as possible while still addressing concerns over control.

Layer 7′s new APIfy service fits perfectly in this space as it allows small teams within the enterprise to get their private or public APIs out the door with a cloud-based API Management solution. They will get all the benefits of rate limiting, controlled access and the developer-friendly portal experience that are the hallmarks of a real Web API, in a SaaS platform. The fact that it is cloud-based means that smaller groups will be able to focus on delivering the solution without diving deep into hosting and implementation details.

Amidst all the decision making, strategizing and private API launches, the steady drum beat of progress towards open APIs in the enterprise has not stopped. The idea that information and services need to be shared in order to be valuable is taking root amongst thought leaders in the mainstream technology world and is, in turn, being heard within the enterprise. For example, Gartner has just published a research article claiming that financial institutions should be investing in APIs rather than applications (with API Management technology addressing the issues around control). Just as online banking started with private connections before it eventually landed on the public Web, the big banks could shift from private API adoption to public API adoption very quickly if the market demanded it. When banks open up their services for controlled consumption, there will be little doubt that the open API era has arrived for the enterprise.

It hasn’t gotten any easier to become an open API enterprise over the last three months but it certainly isn’t becoming less important. Hopefully, continued improvements in API Management technology will make that shift just a little bit easier.