Introductions to APIs

Introduction
An API defines the way in which computer systems interact.

Web API - built to be explored over a network and used

remotely by lots of different people or entities.

A web API exposes the powerful functionality while hiding the

computational requirements from consumers.

Human interacts with a system via GUI (through API)

System to System interaction can happen via API because while

humans can adjust with changed GUI, a computer can not cope
with GUI.

Thus, APIs are interfaces specifically for computers with

important properties to make it easy for computers to use

Introductions to APIs 1
 them

Assembling APIs in a system, orderly and logically, can solve

complex larger problems. An API can be considered like a Lego
building block.

Resource Orientation
An act calling predictWeather(postalCode=574226) and
receiving response in return is RPC (some actions will be
performed)

Ex: RPCs like

ScheduleFlight() → “fight”
CancelReservation() → “reservation”
These words are actually synonyms in the context.

Resource Orientation - Standardization of building blocks to

use when designing an API. Solves the above synonyms problem.

Resource orientation (RO): limits actions to a small standard

set - CRUD actions

RO is a special type of RPC style APIs where each RPC follows

a clear and standardized pattern:
standardMethod<Resource>()

1. Create<Resource>()

2. Get<Resource>()

3. LIst<Resource>()

4. Delete<Resource>()

5. Update<Resource>()

Method Resource Resource Methods

Introductions to APIs 2
 Method Resource Resource Methods

Create FlightReservation CreateFlightReservation()

Get FlightReservation GetFlightReservation()

List FlightReservation ListFlightReservations()

Delete FlightReservation DeleteFlightReservation()
Update FlightReservation UpdateFlightReservation()

RO is good for stateful, while RPC for stateless

A good API [SEOP]

Operational: An API must be useful as intended

Expressive: The interface of an API must be clear and

simple

Ie, APIs should be expressive and provide the ability

for users to clearly dictate exactly what they want and
even how they want it done.

Simple:

On the lighter side, reducing the number of

things[calls] in an API

Rather so, APIs should aim to expose the functionality

that users want in the most straightforward way
possible, making the API as simple as possible.

Make the common case easier accessible, simple,

advanced case hidden and less frequent, but possible.

Predictable:

APIs shall not surprise the user.

Case:
dev 1 writes TranslateText() - accepts “text” [Text]

dev 2 writes DetectText() - accepts “text” [NewText]

where Text is different NewText

Introductions to APIs 3
 APIs that rely on repeated, predictable patterns (Eg:
naming fields consistently.) are easier and faster to
do learn and therefore, better.

Predictable APIs are easy to learn and understand.

Summary
Interfaces are contracts that define how two systems
should interact with one
another.

APIs are special types of interfaces that define how two

computer systems inter-
act with one another, coming in many forms, such as
downloadable libraries
and web APIs.

Web APIs are special because they expose functionality

over a network, hiding
the specific implementation or computational requirements
needed for that
functionality.

Resource-oriented APIs are a way of designing APIs to

reduce complexity by
relying on a standard set of actions, called methods,
across a limited set of things,
called resources.

What makes APIs “good” is a bit ambiguous, but generally

good APIs are operational, expressive, simple, and
predictable.

Introductions to APIs 4