How are web APIs designed


APIs as the cornerstone of software development

APIs are the cornerstone of software development and have become known to many non-technicians at the latest since the advent of Web 2.0. But that's where it often ends. What is really behind the term? What exactly are APIs and what is their role on the web? This article is a practical attempt at explanation and a summary for all the uninitiated, in order to be able to confidently speak and make decisions in the future.

While most of them still know that the abbreviation “API” is the English-language term “Application Programming Interface”, non-technicians usually stumble in the dark behind it. Both this fact and the inflationary and incorrect use of the term over the past few years may be the reason why it has grown into a real buzzword.

Web APIs were at times touted as the panacea and secret weapon of every website, and at Web 2.0 heyday they were even considered one of those points on the business plan that could increase the company's valuation by a few significant percent.

Now that this initial euphoria has subsided a bit, we will now clear up rumors and legends, show the real opportunities and risks and provide some insight into the jungle of APIs.

The purpose of web APIs

Although we will learn to differentiate between different types of APIs below, they all have one thing in common: They are used to exchange and process data and content between different websites, programs and providers, and thus enable third parties to access previously locked data pools and User groups. By sharing this content, completely new services (such as desktop clients), added value (such as mash-ups) or even entire ecosystems - such as application stores - can be created.


As you can see from the term, APIs are basically interfaces. An interface enables communication and interaction between two systems. Almost everything in our world consists of interfaces: plugs and sockets serve as interfaces for the transmission of electricity, keyboard and fingers when using a computer to transfer thoughts into digital characters.

The computer world is also teeming with interfaces and APIs - they have always been the cornerstone of operating systems and programs. However, when APIs are talked about in internet circles, what are usually referred to are so-called web service APIs or web APIs, i.e. interfaces for and from websites and web applications. Although we will primarily refer to Web APIs in this article, most of the general facts are common to traditional APIs as well.

User interface vs. application programming interface

In the case of websites and programs, the visual surface, the so-called (graphical) user interface or frontend, serves as an interface between the user and the underlying software logic, the backend. The user interface receives data from the user, forwards it to the software for processing, and then returns the result to the user. The term user interface is not only widely used and known among technicians for a long time - it is the general term for the face and surface of software. It is designed in detail, implemented on the web using technologies such as HTML, CSS or Flash and optimized for usability. Every website displayed in the browser is initially a user interface through which the user interacts with the actual software.

The equivalent of the human-optimized (human-readable) user interface are now the software-tailored (machine-readable) application programming interfaces, which basically enable a more clearly abstracted and structured access to the functions of the backend. In this way, data can be exchanged, for example, in a particularly easy to process and reduced form.

API design and standards

All of this also means: Just as we design and design a website, an API must also be designed and designed. And since the interface ultimately has to be implemented and tested by a person (a programmer), we ideally have to enclose documentation that is understandable for people (or at least for programmers).

The latter three aspects in particular are already defined and standardized by a handful of established standards, so-called protocols, from which API designers should choose.

To standardize the general structure, there are protocols such as SOAP, XML-RPC or REST, which specify the structure - from left to right - depending on the choice, from strict to less strict. So while SOAP is a very complex standard, the simpler REST offers more design freedom. For this reason, SOAP is considered the standard in the enterprise environment, while REST dominates the market for public Web APIs.

Finally, standards such as XML or JSON are usually used for the data format. To draw the comparison to websites again: They are ultimately the API equivalent of HTML.

To differentiate between web APIs

After the basics have been clarified, it makes sense to differentiate between different forms of Web APIs in order to better understand the underlying aspects. In this article we distinguish between four different types of web APIs:

  • Internal APIs
  • External APIs
  • Platform APIs
  • Authentication and Authorization APIs

Internal APIs

Strictly speaking, almost everything in the world of software development is an internal API. The clearer the distinction between code and other modules, the more likely it is to speak of a real interface. Internal APIs are part of the good tone of professional software development and are used to separate components and modules of the software from one another on the one hand and to reconnect them again on the other. This increases the modularity and thereby reduces the overall complexity.

So-called service-oriented architectures (SOA) go particularly far in that they break down the overall system into as many individual, independent sub-systems (services) as possible, which communicate with each other, for example via web service APIs.

Good examples of pronounced modularization outside the software industry can be found, for example, in the automotive and PC industries, which are rewarded with a wide range of work sharing, outsourcing and combination options.

External APIs

When we talk about APIs in general, we usually mean external APIs. Analogous to the presentation of certain functions to the user via the user interface, these and other functions can also be executed via an external API. This is particularly interesting for further processing content and developing mash-ups. A typical example is sending tweets via desktop applications such as TweetDeck, where the external Twitter API is used.

Well-known examples of external web APIs in addition to Twitter are those from Flickr and YouTube. With these, the content of the website can be automatically read, added or changed, which is expressed today in countless freely available tools.

Platform APIs - for example Facebook, OpenSocial

Platform APIs provide interfaces for integration with another website or platform. This allows third parties to develop applications or plug-ins and operate them within the framework of the platform. For this purpose, a platform API offers in particular functions with which the user interface of a developed application can be integrated into the user interface of the platform, but also certain functions for accessing user data (for example the name of the logged in user or that of his friends) or others central functions of the platform.

Well-known examples from the web world are the Facebook API or the OpenSocial standard for platform APIs. Such websites are also referred to as "platform-enabled websites". But also iPhone, Android, Windows, Linux or Mac applications are only possible by opening platform APIs.

Authentication and Authorization APIs

There is also a special type of Web API that is becoming increasingly important: interfaces for authentication (identification) and authorization (granting access rights) of users.

Well-known examples of authentication are Facebook Connect, Google FriendConnect or the OpenID standard, which saves you from having to set up your own user pool by logging in via other platforms. This is also called single sign-on.

In the area of ​​authorization, the OAuth standard has become established, through which the user can determine whether his data is accessible to third parties via APIs (for example whether an external application can post tweets on his behalf).


APIs have become an integral part of today's web world. The increasing openness towards third-party providers is one of the most exciting developments on the web, and will interweave platforms and content into an even denser network. A whole ecosystem of its own is created around the effective development and use of APIs: For example, providers such as Apigee offer extensive analysis and control functions for their own web APIs.