What is an API?

The basics

API is a shorthand for Application Programming Interface, i.e. an ‘interface’ which allows communication between two applications:

1. You address the API (= request)
2. The API executes internal logic, unknown to the user
3. The API sends back information (= response)

High level architecture of the above process:

APIs enable communication between applications

1. One application exposes an API
   • Exposing an API = giving functionality to the ‘outside world’
2. Other applications can consume this API
   • Consuming an API = making use of functionality given by an API (= calling an API and using the information given back by the API)

Biggest advantage: ABSTRACTION

• Your application should not know what happens ‘under the hood’ at the API, only the data you get back matters.
• What happens ‘behind’ the API is not known to the user or the consuming application → business logic of the exposing application is better protected.

☕ Abstract example of an API: the coffee machine ☕

The user wants a latte with extra milk:

1. 🔌 Start the coffee machine
2. ☕ Choose ‘latte’
3. 🥛 Choose ‘extra milk’
4. ✅ Press ‘start’
5. ⏱ Wait until the latte is made

The user does not know what happens inside the coffee machine…

• They chose a latte with extra milk using the touch screen on the coffee machine, but did not specify which internal component of the coffee machine should perform which task.
• The touch screen serves as an API for the coffee machine: the user tells the touch screen what they want, and the touch screen sends this information to the internal components of the coffee machine.

REST vs. SOAP

APIs can be…

• Web services: you interacting with a system using web protocols
• Documentation of programming languages (e.g. Java API): you interacting with a programming language
• Software libraries: you interacting with framework components
• …

We shall focus on the API's as web services. In that case there are multiple protocols which can be used for these web services: REST, SOAP, GraphQL, XML-RPC, …

REST and SOAP are standardized set of rules for web services that use the HTTP protocol. They have many similarities, but also many differences. Other sets of rules exists (e.g. GraphQL), but are not as widely used as REST and SOAP.

🧼 SOAP = Simple Object Access Protocol 🧼

• Language and platform independent
• Works well in distributed enterprise environments
• Standardized
• Provides pre-built extensibility (WS-standards)
• Built-in error handling
• Rather heavy-weight
• Mandatory use of XML

📋 REST = REpresentative State Transfer 📋

• Smaller learning curve
• Supports both XML and smaller message formats (e.g. JSON)
• Fast
• Closer to other web technologies in terms of design philosophy
• +/- 70% of public APIs use REST nowadays

In this course we focus on the latter, REST.