Universidad La Salle
Tecnologías de Construcción de Software
APIs
PhD(c). Vicente Machaca Arceda
2023
Contenido
1
API Paradigms
Request-Response APIs
REST
RPC
GraphQL
Event-Driven APIs
Request-Response APIs problem
WebHooks
WebSockets
HTTP Streaming
Conclusions
PhD(c). Vicente Machaca Arceda | Tecnologías de Construcción de Software
API Paradigms
2
An API paradigm defines the interface exposing backend data of a
service to other applications [1].
Figure: Example of API architecture.
PhD(c). Vicente Machaca Arceda | Tecnologías de Construcción de Software
Request-Response APIs
3
According to Jin [1].
I Request–response APIs expose an interface through an
HTTP-based web server.
I APIs define a set of endpoints.
I Clients make HTTP requests for data to those endpoints and the
server returns responses.
I The response is typically sent back as JSON or XML.
PhD(c). Vicente Machaca Arceda | Tecnologías de Construcción de Software
Tabla de contenido
4
API Paradigms
Request-Response APIs
REST
RPC
GraphQL
Event-Driven APIs
Request-Response APIs problem
WebHooks
WebSockets
HTTP Streaming
Conclusions
PhD(c). Vicente Machaca Arceda | Tecnologías de Construcción de Software
Request-Response APIs
Representational State Transfer (REST)
5
According to Jin [1], Representational State Transfer (REST):
I Is the most popular choice for API development lately.
I REST is all about resources.
I REST APIs expose data as resources and use standard HTTP
methods to represent Create, Read, Update, and Delete (CRUD)
transactions
PhD(c). Vicente Machaca Arceda | Tecnologías de Construcción de Software
Request-Response APIs
Representational State Transfer (REST)
6
HTTP methods like GET , POST , UPDATE , and DELETE inform the
server about the action to be performed. Different HTTP methods
invoked on the same URL provide different functionality:
PhD(c). Vicente Machaca Arceda | Tecnologías de Construcción de Software
Request-Response APIs
Representational State Transfer (REST)
7
REST APIs might return JSON or XML responses.
PhD(c). Vicente Machaca Arceda | Tecnologías de Construcción de Software
Request-Response APIs
Representational State Transfer (REST)
8
Figure: Example of JSON and XML responses
PhD(c). Vicente Machaca Arceda | Tecnologías de Construcción de Software
Request-Response APIs
Representational State Transfer (REST)
9
Standard HTTP response status codes are returned by the server
indicating success or failure.
I 2XX indicate success.
I 3XX indicate a resource has moved.
I 4XX indicate a client-side error (like a missing required
parameter or too many requests)
I 5XX indicate server-side errors.
PhD(c). Vicente Machaca Arceda | Tecnologías de Construcción de Software
Tabla de contenido
10
API Paradigms
Request-Response APIs
REST
RPC
GraphQL
Event-Driven APIs
Request-Response APIs problem
WebHooks
WebSockets
HTTP Streaming
Conclusions
PhD(c). Vicente Machaca Arceda | Tecnologías de Construcción de Software
Request-Response APIs
Remote Procedure Call (RPC)
11
Remote Procedure Call (RPC) is one of the simplest API paradigms,
in which a client executes a block of code on another server.
Whereas REST is about resources, RPC is about actions.
Figure: Example of basic RPC call.
PhD(c). Vicente Machaca Arceda | Tecnologías de Construcción de Software
Request-Response APIs
Remote Procedure Call (RPC)
12
RPC APIs generally follow two simple rules:
I The endpoints contain the name of the operation to be executed.
I API calls are made with the HTTP verb that is most appropriate:
GET for read-only requests and POST for others.
PhD(c). Vicente Machaca Arceda | Tecnologías de Construcción de Software
Request-Response APIs
Remote Procedure Call (RPC)
13
RPC-style APIs are not exclusive to HTTP. There are other high
performance protocols that are available for RPC-style APIs.
PhD(c). Vicente Machaca Arceda | Tecnologías de Construcción de Software
Tabla de contenido
14
API Paradigms
Request-Response APIs
REST
RPC
GraphQL
Event-Driven APIs
Request-Response APIs problem
WebHooks
WebSockets
HTTP Streaming
Conclusions
PhD(c). Vicente Machaca Arceda | Tecnologías de Construcción de Software
Request-Response APIs
GraphQL
15
GraphQL is a query language for APIs that has gained significant
traction recently. It was developed internally by Facebook in 2012
before being publicly released in 2015 and has been adopted by API
providers like GitHub, Yelp, and Pinterest [1].
PhD(c). Vicente Machaca Arceda | Tecnologías de Construcción de Software
Request-Response APIs
GraphQL vs REST
16
Figure: GraphQL vs Rest.
PhD(c). Vicente Machaca Arceda | Tecnologías de Construcción de Software
Request-Response APIs
GraphQL vs REST
17
GrapQL REST
Performance Fast Multiple network calls
take up more time
Query complexity Query can become Since there are sepa-
very complex be- rete endpoints for dif-
cause of different ferent queries. The
client’s request queries are simple
Popularity Still growing Very popular
Resource & com- Growing Large
munity support
Learnin curve Steep kearning curve Very simple learning
curve
File uploading No Yes
Web caching Uses web library Inbuilt
Recommended use Multiple microser- Simple apps and re-
case vices and mobile source driven appli-
apps cations
PhD(c). Vicente Machaca Arceda | Tecnologías de Construcción de Software
Request-Response APIs
GraphQL vs REST
18
Figure: GraphQL vs Rest.
PhD(c). Vicente Machaca Arceda | Tecnologías de Construcción de Software
Request-Response APIs
GraphQL vs REST vs RPC
19
REST RPC GraphQL
What? Exposes data as Exposes action- A query language
resources and based API meth- for APIs —clients
uses standard ods—clients pass define the struc-
HTTP methods to method name ture of the re-
represent CRUD and arguments sponse
operations
Example Stripe, GitHub, Slack, Flickr Facebook,
services Twitter, Google GitHub, Yelp
Example GET users<id> GET query ($id:
usage users.get?id=<id> String!) {
user(login: $id) {
name company
createdAt } }
HTTP GET, POST, PUT, GET, POST GET, POST
verb uses PATCH, DELETE
PhD(c). Vicente Machaca Arceda | Tecnologías de Construcción de Software
Request-Response APIs
GraphQL vs REST vs RPC
20
REST RPC GraphQL
Pros
I Standard I Easy to I Saves
method understand multiple
name, I Lightweight round trips
arguments payloads I Avoids
format, and versioning
status codes I High
performance I Smaller
I Utilizes
payload size
HTTP Strongly
features typed
I Easy to itemBuilt-in
maintain introspection
PhD(c). Vicente Machaca Arceda | Tecnologías de Construcción de Software
Request-Response APIs
GraphQL vs REST vs RPC
21
REST RPC GraphQL
Cons
I Big payloads I Discovery is I Requires
I Multiple difficult additional
HTTP round I Limited query
trips standardiza- parsing
tion I Backend
I Can lead to performance
function optimization
explosion is difficult
I Too
complicated
for a simple
API
PhD(c). Vicente Machaca Arceda | Tecnologías de Construcción de Software
Request-Response APIs
GraphQL vs REST vs RPC
22
REST RPC GraphQL
When to For APIs doing For APIs ex- When you need
use? CRUD like opera- posing several querying flexi-
tions actions bility; great for
providing query-
ing flexibility
and maintaining
consistency
PhD(c). Vicente Machaca Arceda | Tecnologías de Construcción de Software
Tabla de contenido
23
API Paradigms
Request-Response APIs
REST
RPC
GraphQL
Event-Driven APIs
Request-Response APIs problem
WebHooks
WebSockets
HTTP Streaming
Conclusions
PhD(c). Vicente Machaca Arceda | Tecnologías de Construcción de Software
Event-Driven APIs
24
With request–response APIs, for services with constantly changing
data, the response can quickly become stale (old) [1].
Developers who want to stay up to date with the changes in data
often end up polling the API. With polling, developers constantly
query API endpoints at a predetermined frequency and look for new
data [1].
PhD(c). Vicente Machaca Arceda | Tecnologías de Construcción de Software
Event-Driven APIs
24
With request–response APIs, for services with constantly changing
data, the response can quickly become stale (old) [1].
Developers who want to stay up to date with the changes in data
often end up polling the API. With polling, developers constantly
query API endpoints at a predetermined frequency and look for new
data [1].
I If developers poll at a low frequency, their apps will not have data
about all the events.
I Polling at a high frequency would lead to a huge waste of
resources.
PhD(c). Vicente Machaca Arceda | Tecnologías de Construcción de Software
Event-Driven APIs
25
To share data about events in real time, there are three common
mechanisms: WebHooks, WebSockets, and HTTP Streaming [1].
PhD(c). Vicente Machaca Arceda | Tecnologías de Construcción de Software
Tabla de contenido
26
API Paradigms
Request-Response APIs
REST
RPC
GraphQL
Event-Driven APIs
Request-Response APIs problem
WebHooks
WebSockets
HTTP Streaming
Conclusions
PhD(c). Vicente Machaca Arceda | Tecnologías de Construcción de Software
Event-Driven APIs
WebHooks 27
A WebHook is just a URL that accepts an HTTP POST (or GET, PUT,
or DELETE) [1].
With WebHooks, you can receive updates in real time. Several API
providers, like Slack, Stripe, GitHub, and Zapier, support WebHooks.
PhD(c). Vicente Machaca Arceda | Tecnologías de Construcción de Software
Event-Driven APIs
WebHooks 28
Figure: Polling vs WebHook.
PhD(c). Vicente Machaca Arceda | Tecnologías de Construcción de Software
Event-Driven APIs
WebHooks 29
Failures
I Ensure delivery through retries.
Firewalls
I Apps running behind firewalls can send, but receiving can be
tricky.
Noise
I Many webHooks in a short time ca be noisy.
PhD(c). Vicente Machaca Arceda | Tecnologías de Construcción de Software
Event-Driven APIs
WebHooks uses 30
Uses
I An e-commerce store notifying your invoicing application about a
sale.
I Payment gateway notifying merchants about a payment.
I Version control systems notifying team members about a commit
to a repository.
I Monitoring systems alerting administrators about an error or
unusual activity in a system.
In most cases, WebHooks are used to communicate between servers
or backend-processes.
PhD(c). Vicente Machaca Arceda | Tecnologías de Construcción de Software
Tabla de contenido
31
API Paradigms
Request-Response APIs
REST
RPC
GraphQL
Event-Driven APIs
Request-Response APIs problem
WebHooks
WebSockets
HTTP Streaming
Conclusions
PhD(c). Vicente Machaca Arceda | Tecnologías de Construcción de Software
Event-Driven APIs
WebSockets 32
WebSockets is a protocol used to establish a two-way streaming
communication channel over a single Transport Control Protocol
(TCP) connection [1].
WebSockets can enable full-duplex communication (server and client
can communicate with each other simultaneously).
I Some enterprise developers using Slack APIs prefer to use the
WebSocket API over WebHooks because they are able to
receive events from the Slack API securely without having to
open up an HTTP WebHook endpoint to the internet where Slack
can post messages.
PhD(c). Vicente Machaca Arceda | Tecnologías de Construcción de Software
Event-Driven APIs
WebSocket 33
PhD(c). Vicente Machaca Arceda | Tecnologías de Construcción de Software
Event-Driven APIs
WebSocket 34
Pros
I Bidirectional low latency communication.
I Reduced overhead of HTTP requests.
Cons
I Clients are responsible for connections.
I Scalability challenges.
PhD(c). Vicente Machaca Arceda | Tecnologías de Construcción de Software
Tabla de contenido
35
API Paradigms
Request-Response APIs
REST
RPC
GraphQL
Event-Driven APIs
Request-Response APIs problem
WebHooks
WebSockets
HTTP Streaming
Conclusions
PhD(c). Vicente Machaca Arceda | Tecnologías de Construcción de Software
Event-Driven APIs
HTTP Streaming
36
With HTTP Streaming, the server is configured to hold on to a
specific request from a client and keep the response open so that it
can push data through it [1].
To transmit data over a persistent connection from server to client,
there are two options [1]:
I Set the Transfer-Encoding header to chunked. This indicates to
clients that data will be arriving in chunks of newline-delimited
strings. For typical application developers, this is easy to parse.
I Stream data via server-sent events (SSE). This option is great for
clients consuming these events in a browser because they can
use the standardized EventSource API.
PhD(c). Vicente Machaca Arceda | Tecnologías de Construcción de Software
Event-Driven APIs
HTTP Streaming
37
Figure: Client–server interaction with an HTTP Streaming API. Source: [1].
PhD(c). Vicente Machaca Arceda | Tecnologías de Construcción de Software
Event-Driven APIs
HTTP Streaming
38
Twitter utilizes the HTTP Streaming protocol to deliver data through a
single connection opened between an app and Twitter’s streaming
API.
The big benefit for developers is that they don’t need to poll the
Twitter API continuously for new tweets. Twitter’s Streaming API can
push new tweets over a single HTTP connection instead of a custom
protocol.
PhD(c). Vicente Machaca Arceda | Tecnologías de Construcción de Software
Request-Response APIs
WebHooks vs WebSockets vs HTTP Streaming
39
WebHooks WebSockets HTTP Streaming
What? Event notifica- Two-way stream- Long-lived con-
tion via HTTP ing connection nection over HTTP
callback over TCP
Example Slack, Stripe, Slack, Trello, Twitter, Facebook
services GitHub, Zapier, Blockchain
Google
Pros
I Easy server- I Two-way I Can stream
to-server streaming over simple
communica- communica- HTTP.
tion. tion. I Native
I Uses HTTP I Native browser
protocol. browser support.
support. I Can bypass
I Can bypass firewalls.
firewalls.
PhD(c). Vicente Machaca Arceda | Tecnologías de Construcción de Software
Request-Response APIs
WebHooks vs WebSockets vs HTTP Streaming
40
WebHooks WebSockets HTTP Streaming
Cons
I Do not work I Need to I Bidirectional
across maintain a communica-
firewalls or persistent tion is
in browsers. connection. difficult.
I Handling I Not HTTP. I
failures, Reconnections
retries, required to
security is receive
hard. different
events.
When to To trigger the For two-way, For one-way com-
use? server to serve real-time commu- munication over
real-time events. nication between simple HTTP.
browsers and
servers.
PhD(c). Vicente Machaca Arceda | Tecnologías de Construcción de Software
Tabla de contenido
41
API Paradigms
Request-Response APIs
REST
RPC
GraphQL
Event-Driven APIs
Request-Response APIs problem
WebHooks
WebSockets
HTTP Streaming
Conclusions
PhD(c). Vicente Machaca Arceda | Tecnologías de Construcción de Software
Conclusions
42
You might need to support multiple paradigms. For instance, the
Slack API supports RPC, WebSockets, and WebHooks.
It’s important to understand which solution will work best for your
customers and business goals within the constraints you are working.
PhD(c). Vicente Machaca Arceda | Tecnologías de Construcción de Software
References I
43
[1] B. Jin, S. Sahni, and A. Shevat, Designing Web APIs: Building
APIs That Developers Love. " O’Reilly Media, Inc.", 2018.
PhD(c). Vicente Machaca Arceda | Tecnologías de Construcción de Software
