Application Programming Interface (API)

API stands for Application Programming Interface. An API is a standard connection between computer systems allowing them to exchange data and collaborate easily. Just as people need to speak the same language to understand each other, an API ensures that basic communication between computer systems is well managed. Thanks to APIs, we can quickly add new functions to systems and also connect new systems.

In this ‘API for dummies’, we will first address the question ‘what is an API connection?’ and tell you a bit more about how such an API is structured and used. Then, we provide some examples of how APIs help digitalization within various industries. We also describe the different types of APIs and their characteristics. Finally, we explain the benefits an API offers and show how APIs are used to flexibly connect our HelloID platform to various source and target systems of customers.

What is an API?

Today, we manage more and more things online. With one click on your smartphone or laptop, you can access the news, view your social media, or book a flight, for example. Staying with that last example, such a travel app or website cannot work standalone. Through such an app, you indicate where you want to go, with how many people you want to travel, and when. Then, the app needs access to various airlines to find suitable flights and display them to the customer.

Nowadays, there are countless airlines and travel applications. The last thing we want is to have to write thick specifications for each individual connection between an airline and travel application first. Therefore, APIs have been developed so that travel applications can request information in an agreed manner from such reservation systems. And in a similar way, sites like Booking.com use APIs to include individual home renters in their platform. Another example is health insurers using APIs to easily connect healthcare institutions. And banks make it possible for customers to link their personal account to their online accounting package with an API. APIs are the standard connections that ensure we can connect and collaborate computer systems quickly, safely, and reliably in the current online world. But how does such an API work?

How does API work in practice?

First of all, you must agree on some technical and practical matters in such an API connection to make communication between systems possible at all. For example, we agree that we send all information using the HTTP protocol over the internet. And that we use a certain format for the data, such as XML or JSON. There are several technical standard API formats (such as the REST API) in which such general agreements have already been laid down. Therefore, you do not have to spend much time designing an API; it is mainly a matter of the right choice. Later in this blog, we will further explain some of these technical API formats (the REST, SOAP, RPC, and GraphQL APIs).

What makes each API unique are the data and instructions that systems can send to each other via an API. And there are also agreements about what the receiving system will do with that data. With such an API, you can, in fact, remotely command another system. Hence the term Application Programming Interface: You can, as it were, remotely program an application using instructions that you send to that system via an interface.

You can best compare such an API to the waiter in a restaurant. You order a bowl of soup from the waiter. The waiter then goes to the kitchen and passes the order to the chef. You do not have to walk to the chef yourself, and you do not have to explain to him how to make soup.

How does that work with the connection between the reservation system and the travel app? First of all, they can agree to use a REST API. And over that API, the following things can be exchanged, for example:

• The travel app sends the travel details (destination, date, number of children/adults) to multiple reservation systems via the API.
• The systems search based on the received data for relevant flights, check if there is space and what the prices are. These data are sent back.
• The travel app presents all available flights to the customer.
• If the customer has chosen a flight, the travel app sends a booking request to the respective reservation system. The system processes that request and books the flight.
• The reservation system sends a confirmation and also provides payment instructions. Etc. etc.

With the help of this API, we know how the travel app and the reservation systems technically work together. And the handy thing is that if airlines receive new connection requests from other travel apps, they can use the same API. All details are already laid down in the API, and it is almost plug and play.

Example of an API

Similar to the above example in aviation, you find countless APIs in all sectors. Sometimes they are APIs used sector-wide to connect applications. But there are also more universal APIs that are used much more broadly. For instance, if you want to use Google Maps on a website or in an application, you can do this with the established Google API. Below we give some examples of APIs used in different sectors.

API in healthcare

Healthcare is digitalizing at a rapid pace. Healthcare institutions use numerous systems, ranging from regular office automation to specific healthcare applications and medical systems. Often, it concerns standard software used in different organizations and must be able to be connected in various ways to other systems. Nedap Ons is an example. Nedap Ons is a comprehensive software solution for streamlining administrative tasks in healthcare organizations. It includes features for managing information about both employees and clients, planning, and authorization. To connect Ons to other systems, Nedap offers a REST API that gives other systems access to services and data in the Nedap Ons platform.

API for the government

Municipalities are complex organizations with a multitude of systems. Many of the tasks involve longer-term issues such as a permit application, a subsidy request, or a passport renewal. These matters are managed with a so-called case system in which all relevant data about such a case are stored. A case system needs many interfaces. For example, with the KCC (Customer Contact Center) so that questions from citizens can be answered quickly and adequately. Other municipal ICT systems also consult information from such a case system. That is why it is now prescribed that case systems use the so-called ‘APIs for Case-oriented working’. Municipalities no longer need to copy data between systems; they can always consult data directly in the source system. It is an example of a municipal API to accelerate the digitalization of municipalities.

API for the business market

Human Resources (HR) is gradually playing an increasingly important role in companies. Previously, it was mainly the administrative ‘personnel department’. But now the role is much more about finding and retaining talent. Also, in more and more processes, from payroll to the issuance of user accounts, the HR system is used as the leading source system. Therefore, modern HR systems such as AFAS and Visma have APIs to disclose HR data to other systems. Visma Raet, for example, is aimed at government organizations, healthcare and educational institutions. The system offers, among other things, the Visma.net HRM & Payroll API for connections with systems and applications developed by the organization itself and third parties.

The difference between APIs and Webservices

Sometimes the terms API and webservices are used interchangeably. Good, therefore, to also clarify that term. With a webservice, you can make applications accessible to external systems via the internet. A webshop, for example, does not have to build its own payment functions. It can easily be linked to a payment provider that handles the payments with the help of a webservice.

’A webservice thus acts as an API between the payment provider and the connected webshops. But it is a very specific type of API. Such a webservice is purely intended for communication via the internet, its use is laid down in a specific format (Web Service Definition Language, WSDL) and it always uses certain standards such as SOAP, HTTP, and XML.

A webservice is thus one of the different types of APIs used today. There are also plenty of APIs that work differently. For example, they use other types of networks, other standards, or other data formats. Moreover, there are also APIs that do not use a network at all and are used to connect systems directly. And finally, there are also APIs that allow different applications within one system to work together. For instance, an operating system like Windows has countless APIs to let various applications, peripherals, etc., work together on your computer. A webservice is thus an API, but not every API is a webservice.

Different types of APIs and benefits

What is a REST (JSON, XML, HTML) API?

REST stands for Representational state transfer. The REST API – or more fully: RESTful API – was developed in 2000 and is popular because of its flexibility. The information can be sent over different protocols although – especially in web environments – the HTTP protocol is usually used so no extra API software is needed to use it. Standard HTTP methods such as GET, POST, PUT, and DELETE can be used and because short messages are used REST APIs are relatively fast. A REST API is also stateless; it stores no session information so every request to a system must contain all necessary information.

REST APIs support different data formats. Not only JSON (JavaScript Object Notation) which with its relatively light, simple structure is popular in web environments. Also, the more structured XML (eXtensible Markup Language) format that is mainly used for more complex data. In addition, HTML (HyperText Markup Language), the markup language for web pages, is an option. REST APIs are particularly suitable for ‘lightweight’ APIs and are used in a wide range of online services, from X to Spotify.

What is a SOAP (XML) API?

Simple Object Access Protocol (SOAP) is already a veteran among the protocols; SOAP has now existed for 25 years. SOAP APIs are mostly used for webservices and use the HTTP protocol. However, there are also legacy SOAP connections that transport the information over SMTP (Simple Mail Transfer Protocol).

SOAP uses XML. As sketched above, it is a more structured information format, which makes messages longer and data exchange slower. SOAP is a bit ‘heavy’ for simple web applications but very suitable for supporting complex data exchange and processes in Enterprise environments. SOAP also offers more advanced security measures. With these properties, SOAP is widely used in, for example, payment services and communication between banks and other large business environments.

What is an RPC (TCP, UDP) API?

RPC stands for Remote Procedure Call. This is a somewhat older approach and you can argue whether it is really an API. We compared an API earlier to the waiter in the restaurant, a kind of ‘man-in-the-middle’. If you extend that comparison, you can better compare RPC to a restaurant visitor who yells directly at the chef that he wants soup. With RPC, an application can directly call functions within the receiving system. This has advantages – it is direct, fast, and powerful – but the communication is not standard secured and also not very flexible. If you want the system to do something else, you have to adjust the interface again. The communication goes via TCP (Transmission Control Protocol) or UDP (Datagram Protocol).

What is a GraphQL (HTTP) API?

GraphQL was developed by Facebook and is interesting because of the extensive filtering options and you can also send commands to different systems simultaneously. In fact, you can already filter exactly which information you are looking for in a query to the system, and only that data are then sent back. The complexity of multiple connected systems is shielded from you and you receive the coherent results of your query.

Overview table

	REST API	SOAP API	RPC API	GraphQL API
General	Based on standard HTTP methods (GET, POST, PUT etc.)	Uses XML, normally via HTTP	Simple procedure calls via direct function calls	Query language to distributed systems
Data Formats	JSON, XML or HTML. Other options possible	XML	XML, JSON. Other options possible	Often JSON, but can support other formats
Protocols	Normally HTTP protocols, other options possible	Can use various protocols, such as HTTP, SMTP, etc.	Usually TCP or UDP	Uses HTTP, underlying protocol may vary
Stateful or Stateless	Always stateless	Stateless and Stateful	Stateless and Stateful	Normally stateless, but can be stateful
Flexibility	More flexibility in endpoint URLs and data formats	Less flexible, requires explicit definition of data structures and actions	Less flexible, as it directly calls methods	Offers a high degree of flexibility and allows the client to specify the required data
Speed	Generally faster due to less overhead	May have more overhead, making it slower	Can be fast due to direct calls to the target application	Efficient as it only fetches the required data
Security	Supported but pay attention to the implementation of authentication and authorisation	Can offer complex security options (e.g., WS-Security)	Requires additional security measures	Provides field-level security

Benefits of using an API

With the help of APIs, we can easily combine functions from different systems to create new applications. You reuse as much as possible existing applications and functions so you can focus on the new matters. In the example of the travel app, the owner can fully focus on the development of the app while we use the existing functionality and standard API connections as much as possible for the flight data from reservation systems. This way, we can concentrate on what you really want to develop new, while the implementation of the solution as a whole is manageable, safe, and flexible. We explain this below a bit further.

Sense of control

Digital innovation depends on the ability to easily let different systems work together. So you can easily reuse existing functionality or easily consult data from other systems. At the same time, it must happen in a controlled manner. If we make ad hoc connections between all kinds of systems and directly tap into each other’s software and data, we end up with a ‘spaghetti architecture’ in no time; an architecture in which the slightest adjustment causes the functionality, reliability, or security to start rattling.

A good architecture with well-developed and documented APIs gives systems controlled access to each other’s functionality and data. The system owner always remains in control over how those matters can be used and other systems also never get direct access to the code. Also, system adjustments are no problem at all. Via the existing APIs, existing functions and data remain accessible, while new functionality can also be made accessible as needed via an update of such an API. The system as a whole is ‘under control’.

API Security

Importantly, modern APIs form an integral part of your information security. Before we all started working remotely and hybrid, corporate networks were often still secured like a castle. In such a castle, the walls and the gate provide the security but behind that, there is little more to stop intruders. In a similar way, IT managers focused entirely on the access security to their corporate network. Once inside that network, there was little control over user behavior and also the connections between systems were often simply completely ‘open’. Now that we all work remotely and in the cloud, this traditional access security is no longer sustainable.

Zero-trust principle

IT applications can be accessed remotely by users and systems also have contact with systems outside their own organization via the internet. Therefore, modern IT networks must be based on the zero-trust principle, where we never blindly trust something or someone. With every user session – and thus also with information exchange between systems – the question must be who is requesting access, what their role is, and what access rights the system has. Modern web APIs make this possible. How you apply an API securely, we explain below.

Flexibility

Organizations as a whole must be able to respond more quickly to new societal developments, market trends, and technological innovations. IT also needs to be more agile. Applications must be able to be linked quickly or just disconnected. With modern APIs, we support this. Connecting systems rarely requires a lengthy system integration project; usually, an API can be configured and activated quickly.

An example is modern HR systems. They are linked to other company systems via APIs. Often, after a few years, another HR package is selected. If another package is chosen, such a migration can be carried out quickly thanks to the available APIs. Not only can you quickly connect the new application via an API, but also transferring the data to the new system can be efficiently arranged via APIs.

How to securely deploy an API?

As explained before, modern APIs must operate according to the zero-trust concept. We must therefore never blindly assume that they can be trusted in an interface between two systems. Just like users, applications must authenticate themselves (who am I dealing with?) when they request access to another application. And also, a connected system must have the right authorization (what can someone do?) to be able to give commands to that other system. It is increasingly important that we only give people and systems access to functions and data that are really needed. Especially because more and more personal data are being sent between systems.

GDPR rules

The GDPR sets strict rules for this. Systems may only process personal data for clear and justified purposes. That is called purpose limitation and in a good API, you can set the data selection so that only those data can be shared that the receiving application needs. If you link, for example, an HR system to a training tool, such a system does not need absence data. Those data must therefore be closed off for this application.

Tip: Test your API
Authorization is often based on the OAuth 2.0 standard. And precisely because attention is naturally focused on the authentication and authorization of human users, it is extra important to also test the security of APIs.

Efficient API connections for Identity and Access Management

How do we use APIs within an Identity & Access Management (IAM) platform and what IAM APIs are there? We explain this using our cloud-based HelloID platform. As an IAM platform, we have connections with so-called source systems and target systems.

• Source systems are mostly HR systems, such as People Inc and SAP. They feed the IAM platform with information about new employees, function changes, and people leaving service. Based on this information, we create new accounts, manage access rights, and eventually also break down accounts again.
• Target systems are the systems to which we then send information. Once we have registered a user account in HelloID and determined the associated access rights, we also create the accounts in, for example, the Active Directory or Entra ID. We also send account information and settings to business applications such as ChipSoft HiX – a widely used healthcare system – and service management systems such as TOPdesk.

Incidentally, many source systems such as AFAS are simultaneously also a target system. For new employees, HelloID actually creates a self-service account on the HR system to manage their own personal data and view payslips.

200 software connections

IAM thus acts as a spider in the web between all systems. For connecting systems, we now offer over 200 connectors to existing systems. A fundamental aspect of these connectors is their ability to integrate with a wide range of APIs, each with its own specific characteristics and formats. As explained earlier in the article, the nature of these APIs varies significantly – some systems use REST, others SOAP or GraphQL. Moreover, the way data is exchanged and the requirements for querying data can vary greatly per API. For example, one HR system may provide all employee data directly, while another system requires first querying a list of all employees, followed by individual data queries (API calls) per employee.

The main function of a connector within this complex landscape is to standardize these diverse data flows. Regardless of the diversity of APIs and the formats in which they deliver data, the connector transforms these into a uniform format. This ensures that data exchange via different systems is consistent and streamlined. In addition to converting data, a connector can also contain additional logic and controls that contribute to efficient and reliable integration. Through the connectors, HelloID is able to read personal and contract data, and set up accounts and access rights. Our approach with HelloID ensures there is maximum flexibility and that adjustments to the connected systems are normally not necessary. The connector thus forms the bridge between the diversity of APIs and the standardized needs of our IAM platform.

Processing API changes

Does a supplier of a connected system change something in their API? Then we adjust the connector. This may also be necessary if a system API gets more possibilities. With some target systems, HelloID can now only create or delete a basic account due to limitations of the API. Specific access rights must then still be managed via the system itself. For example, in a healthcare system where one must set in the system itself who gets access to which patient data. As soon as such an API is expanded by the supplier, we can adjust our connector and from then on also manage these detailed settings from HelloID.