Application
Programming
Interface

Roncajolo Gerald
Techleader @ Softway Medical
T/ 06 71 50 61 53
grc@necol.org
Nov. 2024
resources:
https://api.necol.org/

Disclaimer

These slides are for educational purposes.
They do not replace reference documentation.

This document is dated November 2024.
If you read this in 2024+, check for depreciation.

What is an API ?

Application Programming Interface

  • A set of functions and procedures that allow an applications to access the features or data of an operating system, application, or other service.
  • A set of clearly defined methods of communication between various software components.

API as a Design pattern

  • It Separates interface from implementation (hide the internal details of how a system works)
  • It allows to change the implementation without changing the interface
  • Façade design pattern
    • A simplified interface to a larger body of code
    • Make software easier and convenient to communicate with
    • Reduce dependencies
    • Wrap a complex or poorly designed APIs with a single well-designed API

Web applications

  • Modern applications often use a Presentation(UI)-Domain(aka business logic)-Data(data access) Layering approach.
    • Separation of concerns
    • Enables modularisation, and in turn maintainability

Clean/Hexagonal architecture

  • Protects the core business logic from external concerns.
  • APIs are at the presentation layer.
  • A frontend application, also at the presentation layer, can call the APIs.

Project structure by domains

  • Your application structure should not depend on technical aspects (e.g. database, framework, etc.)
    But rather on business aspects (e.g. domain, business logic, etc.)
  • Each team is responsible for a specific business domain
  • Teams should be full stack

Learn more

Why use APIs in a web application ?

Why use APIs in a web application ?

  1. Enable mobile as an additional channel
  2. Grow ecosystems: customer (B2C) or partner ecosystems (B2B)
  3. Develop massive reach for transaction or content distribution
  4. Power new business models
  5. Generate internal innovation

What different kinds of APIs are there in Web Applications ?

Different kinds of APIs

  • REST
  • SOAP
  • GraphQL
  • gRPC
  • WebSockets
  • Webhooks
  • ...

REST

REST is the most popular API type at the moment, but there are others.
It is important to understand the differences between them, and when to use which.
This is the kind we'll focus on in this training.
It mainly uses JSON as a serialization format, and HTTP as a transport protocol.
It has the advantage of being very simple, and therefore easy to implement.
It is easy to cache, and therefore very scalable.
It has some limitations though, which we'll see later.

SOAP

SOAP is a legacy API type, but it is still used in some enterprise applications.
It is XML based, and uses HTTP as a transport protocol.
It has the advantage of being very strict, and therefore easy to generate client code for.
It has the drawback of being very verbose, and therefore not very efficient.
It is also very complex, and therefore not very easy to implement.
It does not provide explicit support for caching, and therefore not very scalable.

GraphQL

GraphQL is a more recent API type, that is gaining popularity.
It is a query language for APIs.
It is not a protocol, but rather a specification for how to query an API.
It usually uses HTTP as its transport protocol, and JSON as its serialization format.
It has been developed as an alternative to REST, to address some of its shortcomings.
Among them, the fact that REST APIs are often over- or under-fetching data.
GraphQL allows the client to specify exactly what data it needs.
It is often used when bandwidth is limited, for example on mobile devices.

gRPC

gRPC is a more recent API type, that is gaining popularity.
It is a remote procedure call framework.
It is not a protocol, but rather a specification for how to call a remote procedure.
It relies on upon HTTP/2, and uses Protocol Buffers as a serialization format.
It has the advantage of being very efficient, and therefore very scalable.
It has the drawback of being very complex, and therefore not very easy to implement.
It is often used when performance is critical, for internal APIs in a microservices architecture for example.

WebSockets

WebSockets is a technology that allows for full-duplex communication over a single TCP connection.
It is not a protocol, but rather a specification for how to establish a persistent connection.
It is often used as a transport protocol for other APIs, such as REST or gRPC, when the client needs to receive notifications from the server.

Webhooks

Webhooks is a technology that allows for event-driven communication.
It is not a protocol, but rather a specification for how to send notifications.
It is often used as a transport protocol for other APIs, such as REST or gRPC, when the server needs to send notifications to the client.
It is often used when the client is not reachable from the server, for example when the client is behind a firewall.
It can also be used when the treatment of the request is too long to be done synchronously.

We'll focus on REST APIs in this training.

REST APIs rely on HTTP, so we'll start by looking at HTTP.

For example, when you write an application, your application will call the APIs of libraries you use. In turn, the library will call the APIs of the operating system it is running on. Your application may also call APIs of other applications, such as a database server, a web server, or any other server you may have. Your application may also expose APIs that other applications can call.

therefore without breaking the client code

For example, if you'd want to do some cryptography in your application, you could use the OpenSSL library. But the OpenSSL API is quite complex, and you'd have to learn a lot about cryptography to use it. So instead, you could use a library that wraps the OpenSSL API with a simpler API. Why is decoupling important ? => A software is ever evolving, and decoupling leads to better maintainability.

So you often see web applications divided into a web layer that knows about handling HTTP requests and rendering HTML, a business logic layer that contains validations and calculations, and a data access layer that sorts out how to manage persistent data in a database or remote services. The client (browser) calls the web layer, which calls the business logic layer, which calls the data access layer, which calls the database.