RESTful APIs

What is an API?

• API: Application Programming Interface
• Rules to communicate with other software systems
• Create/expose API's to communicate with applications
• Within API context:
  • Application: Piece of software with a distinct function (broad)
  • Interface: Contract of service between two different applications (defines how they will communicate with requests and responses)
• API documentation is typically in depth, and will tell the user how to use the API to formulate requests/responses to enable communication

Why Do We Need APIs?

Efficiency:

• Offload complex processing tasks to third-party services
• Example: Stripe payments API

Innovation

• Access to data/functionality normally out of reach
• Reduce duplicated work

Interoperability

• Enable a standard way for software systems to communicate
• Combine data/services from multiple sources into a single application/tool

What is an API: Client

• Users who want to access information
• Person/Software System
• Example: Weather Data
  • Person can go to their browser and open a weather website
  • Developer can create a program which accesses that data from the site

What is an API: Resources

• The information applications provide to the client
• Can be images, video, text etc. (Any type of data)
• The machine which gives the resources is the server

Example API Architectures

Rest:

• Common/widley used
• Simple
• Handles many requests
• Doesn't support complex queries

SOAP:

• Supports complex queries
• Complex to use
• Not as scalable/performant

Websocket:

• Persistent connections
• Faster than HTTP
• Can push data from server to client without a request

GraphQL (Architectural Style/Query Language):

• Works with any language/framework
• Complex to understand
• Poor error handling
• Prevents over-fetching

What is REST

• WEB API type! (There are other types)
• Representational State Transfer
• Imposes certain conditions on how an API should work
• Guideline to manage communication
• Supports high-performance, and reliable communication at scale

CRUD

• Create: Post
• Retrieve: Get
• Update: Put
• Delete: Delete

The CRUD operations are the 4 operations that a persistent storage application should be able to execute, REST uses the HTTP methods, Post, get, put and delete respectively for these operations

REST Principles: Uniform Interface

• Implies a information transfer in a standardised format
• The formatted resource is known as a representation in REST
• This format may be different to the internally stored representation The server might store data as text for example, but send it in an HTML representation format

Uniform Interface Continued:

1. Requests should identify resources (specify resource location)

2. Clients with a representation (including attached meta data), have enough information to modify/delete the resource on the server

3. Self-descriptive messages are provided by the server, which detail how to process the representation

   • For example, the ContentType may be text/html, which tells the client how to handle to provided representation. Else if the content was JSON, but the client was expecting text/html, it would not be able to process the representation correctly

4. Clients receive information about related resources. Through hyperlinks in the representation

   • If text/html were returned as we requested a webpage, there may be hyper links, that when clicked will perform a GET request to some other API. Or if there is an image tag, this GET request will be immediately triggered so that the image can be served to a user.

REST Principles: Statelessness

• Server completes each request independent of previous requests
• REST API implies the server can fulfil the requests each time
• Resources can be requested in any order

REST Principles: Layered System

• Servers can pass requests to other servers
• Your architecture can include multiple layers (Security, application, business logic etc)
• The server will still fulfil client requests

REST Principles: Cacheability

• Process of storing some responses on the client (or intermediary)
• Example: Webpage which has common header/footer for all pages
• API responses can be defined as cacheable/non-cacheable

REST Parameters: Code on Demand

• Servers can extend/customise client functionality
• Transfers code to the client
• Example: Registration form on a website, browser highlights mistakes

The server can send code the be executed by the client. Like sending javascript to a browser.

API Breakdown

Base URL

"www.thecocktaildb.com/api/json/v1/1/search.php?s=margarita" "www.thecocktaildb.com"

All requests to this api will have the same base url

Endpoint

"www.thecocktaildb.com/api/json/v1/1/search.php?s=margarita" "/api/json/v1/1/search.php"

The endpoint is where the specific resource we want is located. Here the API key is used ('1'). This is a free demo key, but paid users might get more functionality, and will have their own unique key

Query Parameter

"www.thecocktaildb.com/api/json/v1/1/search.php?s=margarita" "?s=margarita"

The query parameter is a way to perform an action on the requested resource, in this case it is a search (denoted by the '?s') which has the value of margarita, and therefore will return what comes as a result from that search

RESTful API Benefits

• Scalability
• Flexibility
• Independence

REST optimises client-server interactions. Server load is reduced, as the server doesn't retain past client information (statelessness). Decoupled server/client components - they can grow separately.

Live Demo - 25 mins