top of page

The API, the Webservice & a short explanatory Story for the Non-programmer - PART 3

Furthering the ongoing article from Part 1 to Part 2 and to the current final article of Part 3 on APIs - An experiment in technical writing for the non-programers. We now need to know how to authorize anyone to access information over the internet via an API & Jump over legally - "NO UNAUTHORISED ENTRY"


Unauthorized entry board

API Access


There are two important API access concepts to access information or content over the internet via APIs as;

  • Authentication: You need to prove your identity.

  • Authorization: You will be allowed to only access the info you are entitled to.

Think of a secret club where only members are allowed inside. If you are a member of the club, you need to show your member ID card to the manager at the door. This is like authentication. It's a way of proving that you are who you say you are.


Now, once you're inside the club, you might have different levels of access depending on what you're allowed to do. For example, you might be allowed to play games in the game room, but not allowed to go into the bar to pour drinks. This is like authorization. It's a way of determining what you're allowed to do once you've been authenticated.


Options available in a club

In an API, authentication is the process of verifying that the person or application making the API request is who they claim to be. Authorization is the process of determining what that authenticated user or application is allowed to do with the API, such as read data or make changes to it.


So, just like the manager at the club needs to see your ID card to let you in, an API might require a username and password, an API key, or other credentials to authenticate a user or application. And once that user or application has been authenticated, the API will determine what they're allowed to do based on their permissions or roles.


Types with Examples of Authentication & Authorization


In the table below we explain different types of authentication or authorization with an example for better understanding;

Name

Authentication

Authorization

Examples

No Auth

(No Authentication)

No

No

Google search page

Basic Auth

(Basic Authentication)

Yes

No

email Account

Bearer Token

No

Yes

Not many

OAuth

(O Authorization)

Yes

Yes

Many (like Twitter, LinkedIn, Dropbox)

Two-factor Authentication

Yes

Yes

High Security (Banks, Gov. )

Mobile Apps & APIs


You must be curious for now to have some insights regarding how APIs interact with your smartphones. To start off with, there are 3 types of mobile applications, notably;

  • Native Apps

  • Web Apps

  • Hybrid Apps


Types of mobile apps

Native Mobile Apps


Native mobile apps are like custom-made toys, especially for you. When developers make native apps, they build them specifically for a particular operating system like iOS or Android. It means that if you have an iPhone, you'll download it from the Apple App Store, whereas for Android from the Google Play Store. Native apps are built with programming languages like Swift or Objective-C for iOS and Java or Kotlin for Android.


Native apps are generally faster and smoother because they're designed to work perfectly with your phone's hardware and software. They can use all the features of your phone like camera, GPS, and contacts.

Some examples of native apps are Facebook, Zomato, and Snapchat.


Web Mobile Apps


Web mobile apps are like games you can play on the ground with your friends, anywhere. They're not installed on your phone like native apps, but you can access them through your phone's web browser like Chrome or Safari. Web apps are designed to work on different types of phones, so they're more like websites than apps. They're built using web technologies like HTML, CSS, and JavaScript, so they can be accessed from any device with an internet connection.


Web apps are usually slower than native apps because they're not designed to work specifically with your phone's hardware and software. They don't have access to all the features of your phone like the camera or GPS.

Some examples of web apps are Google Maps and Gmail.


Hybrid Mobile Apps


Hybrid mobile apps work on all different types of phones. They're created by taking a web app and wrapping it up like a present to look and feel like a native app. This means they can have some of the benefits of native apps, like using your phone's camera or GPS, while still being accessible from any device with an internet connection.


Hybrid apps are built using web technologies like HTML, CSS, and JavaScript, but they're wrapped up using tools like Apache Cordova or Ionic to look and feel like a native app. Some examples of hybrid apps are Twitter, Instagram, and Airbnb.


So, to summarize; Native mobile apps are like toys made specifically for your phone, web mobile apps are like games you can access through your phone's web browser, and hybrid mobile apps are like toys that can work on all different types of phones by wrapping up a web app like a present.


Now, as you have a decent knowledge of mobile apps, here we brief about different kinds of operating systems that run on machines, only the famous one;

  • For Computers - Windows, Mac OS X (Apple), and Linux

  • For Smart Phones - Android and iOS

So now what's with that, the interesting part is these "Operating Systems" mentioned above allow access to APIs to use mobile phone features, which are broadly categorized into the following levels;

  • High-level APIs e.g. These are used to access the calendar, push notifications, browser, email, contacts, etc.

  • Low-level APIs e.g. These are used to access the location, microphone, camera, speaker, calls, touchscreen, etc.

I conducted a brief qualitative analysis of the stated apps as shown in the table below for easy reference;

Native

Hybrid

Web

Quality

Best

Speed

Fastest

Cost

Cheapest

Google play store

Compulsory

Compulsory

Device Access

Best

Okay

Next will delve into the most used authorization method - OAuth.


OAuth


OAuth stands for "Open Authorization". It's a security protocol that allows you to give permission to one website or app to access your information on another website or app, without giving away your password or other sensitive data. It is the most commonly used API access method. It's in RFC Note 6749 where RFC stands for Request for Comments by Internet Engineering Task Force (IETF).


OAuth is like borrowing a toy from a friend. Imagine your friend has a really cool toy that you want to play with, but your friend doesn't want to give it to you forever. They just want you to use it for a little while and then give it back.


OAuth works the same way but with websites and apps instead of toys. When you use a website or app, sometimes they need to access information from another website or app. Via OAuth the other website or app says it's okay for your website or app to use the information, but only for a limited time and only for specific things. Then, when the time is up, your website or app has to give the information back. This helps keep everyone's information safe and private, just like how you wouldn't want someone to take your toy and never give it back.


Why OAuth?

  • To resolve the problems in giving credentials to the third party

  • OAuth helps in introducing an authorization layer

  • Instead of credentials, the third party gets an access token

  • The use of common standards helps make HTTP a must-use.

The OAuth works as simply as the below-listed steps;

  • Client > Asks > Authorization Server > Access token

  • Client > Access token > Resource Server > Gets the resource

OAuth visual workflow

Below is the protocol flow from RFC Note 6749 explaining the entire flow in detail;

RFC note for Oauth authorization

The client gets two tokens in general;

  • Access Token

  • Refresh Token - it refreshes the expired access token & is optional.

Note on OpenID Connect


OpenID Connect (OIDC) is an authentication protocol that provides a secure and reliable way to authenticate users in web and mobile applications. It is built on top of the OAuth 2.0 framework, which is used for authorization.


The primary goal of OIDC is to allow a user to authenticate with a service provider (such as a website or application) using their identity from an identity provider (such as Google or Facebook). This process is called "federated authentication", and it allows users to authenticate with multiple services using the same set of credentials, rather than having to create a separate account for each service.


OIDC Work Flow

  1. The user attempts to log in to the service provider.

  2. The service provider sends a request to the OIDC provider to authenticate the user.

  3. The OIDC provider authenticates the user and generates an ID token, which contains information about the user (such as their name, email address, and profile picture).

  4. The OIDC provider sends the ID token back to the service provider.

  5. The service provider verifies the ID token to ensure that it was issued by a trusted OIDC provider and that it contains the necessary information.

  6. If the ID token is valid, the service provider considers the user authenticated and allows them to access the service.

  7. In addition to providing a standard way to authenticate users, OIDC also provides a mechanism for transmitting user attributes and user data between the service provider and the OIDC provider. This can be used to enable features like single sign-on (SSO), where users can authenticate once and then access multiple services without having to log in again.

Below is the snapshot of a screen you often get to allow for specific data that needs to be shared for an application to provide you with login via Google, Facebook, etc.

google authentication in login

Overall, OIDC is a powerful and flexible protocol that enables secure and easy-to-use authentication for web and mobile applications, making it a popular choice for developers and service providers alike.


Use Cases


Few real-life web and mobile applications that use OAuth and OpenID Connect (OIDC);

  • Facebook: Facebook uses OAuth 2.0 to allow users to log in to third-party applications using their Facebook credentials. This allows users to easily access multiple services without having to create separate accounts for each one.

  • Google: Google uses both OAuth 2.0 and OpenID Connect (OIDC) to enable federated authentication across its services. For example, users can log in to Google Drive using their Google credentials, or they can log in to a third-party service using their Google account via OIDC.

  • Slack: Slack uses OAuth 2.0 to allow users to log in to third-party applications and services using their Slack credentials. This allows users to easily integrate their Slack account with other tools and services in their workflow.

  • Microsoft Azure: Microsoft Azure uses OpenID Connect (OIDC) to provide federated authentication across its services. This allows users to log in to Azure and access multiple services using their Microsoft account.

In summary, OAuth is used for authorization and resource sharing, while OIDC is used for authentication and user identity management. OAuth and OIDC are often used together, as OIDC builds on top of OAuth to provide a comprehensive identity solution for web and mobile applications.


Other Types of API Access


Basic Authentication


As it sounds basic authentication is a simple way of proving your identity. It uses passwords & usernames to access the required API. It started way back in 1999 and is not a very secure way of transaction over the internet.


Digest Authentication


Digest stands for something that can be converted into a usable form. So in the case of Digest Authentication, it's a way of proving your identity by using a digest where the API gets access using a digest. It can use HTTP unlike Basic Authentication and is rarely used nowadays.


Bearer Token


The bearer token originated in 2012 and is part of the OAuth specification. The bearer token is a way of giving permission to access something without having to reveal any sensitive information like usernames or passwords. It's a simple way to access APIs via a token and must use HTTPS rather than HTTP.


The wristband

A bearer token is like a key that allows someone to access a specific service or resource. Imagine you're going to a party and you need to show a special wristband to get in. The wristband is like a bearer token - it allows you to enter the party and access the different activities and services inside.


Similarly, when you use an app or website, you might need to authenticate yourself by providing your username and password. Once you're authenticated, the app or website might give you a bearer token - a special code that identifies you as an authorized user. This token can then be used to access different parts of the app or website without having to constantly re-enter your username and password.


Webhooks & MicroServices


Webhooks


As by the word you can infer web is a web service and a hook is connected to an event. A webhook is a special type of message that one computer sends to another to let it know that something has happened. It's like a "Hey, something just happened!" message that helps different programs work together.


An example of an online store that uses Razorpay to process payments. When a customer buys a product, Razorpay sends a webhook to the online store's website to let it know that the payment has been processed. The webhook might include information about the payment, such as the customer's name, the product, and the amount. The online store can use that information to fulfill the order.


Without the webhook, the online store's website would have to constantly check with Razorpay to see if any payments had been made. This would be inefficient and slow. By using a webhook, Razorpay can tell the online store immediately when the payment has been made, so the order can be fulfilled quickly and efficiently.


MicroServices


The APIs can be structured in two styles one is a monolith structure where a single API does all the tasks where as Microservices where multiple APIs execute a required task.


Imagine you're building a big LEGO castle. The question is - Would you build the entire castle at once or build it in smaller pieces and assemble it together? When you choose to build in smaller pieces, like a tower or a wall, and then put them together to make the whole castle. Each of these pieces can be built by different people, which can make building the castle faster and easier.


In the same way, microservices are small, independent programs that work together to make a big application. Each microservice does its own job, like handling payments or sending emails. They work together to create a larger application that can do many different things.

Just like how LEGO pieces can be combined in different ways to make different things, microservices can be combined in different ways to create different applications. And just like how LEGO pieces can be taken apart and replaced easily, microservices can be changed and updated easily without affecting the whole application.


The advantage of Microservices is that it's scalable, code language independent with smaller and specialized teams. In comparison, the disadvantage is its lack of consistency.


Netfix office

A famous example of microservices in real life, which I guess almost everyone use is Netflix.

I hope you all know that Netflix is a streaming service that delivers movies and TV shows to millions of users around the world. To handle this huge traffic, Netflix uses a microservices architecture.


Each microservice at Netflix does a specific job, such as managing user profiles, handling payment transactions, or recommending content to users. These microservices work together to provide a seamless experience for the user. For example, when you log into Netflix, the service uses a microservice to check your login credentials, another to retrieve your viewing history, and another to recommend content based on your viewing habits. Each of these microservices is independent and can be updated or replaced without affecting the others.


This microservices architecture allows Netflix to scale quickly and handle large amounts of traffic without affecting the service's overall performance. It also allows Netflix to innovate and add new features more easily by building and deploying new microservices independently.


Happy Binge Watching! The End.


-----


All the related articles for "The API, the Webservice & a short explanatory Story for the non-programmer"

  1. Part 1

  2. Part 2

  3. Part 3

-----


Source:

Image 1: Unauthorized entry, Unsplash

Image 2: Club entrance, Unsplash

Image 3: https://www.charterglobal.com/understanding-the-3-types-of-mobile-apps-development-services/

Image 4: https://docs.oracle.com/cd/E50612_01/doc.11122/oauth_guide/content/oauth_intro.html

Image 5: https://www.ietf.org/rfc/rfc6749.txt

Image 6: https://platform.zapier.com/docs/oauth

Image 7: Wristband, Unsplash

Image 8: Netflix office, Unsplash


Source

https://medium.com/swlh/hybrid-vs-native-apps-and-how-to-choose-1d1ed0350fe8

https://developers.google.com/maps/faq#:~:text=The%20Google%20Maps%20Platform%20is%20available%20for%20Android%2C%20iOS%20or,generate%20using%20the%20Cloud%20Console.

https://www.ietf.org/rfc/rfc6749.txt

https://docs.oracle.com/cd/E50612_01/doc.11122/oauth_guide/content/oauth_intro.html

https://www.udemy.com/course/api-and-web-service-introduction/

https://en.wikipedia.org/wiki/List_of_HTTP_header_fields

https://developer.mozilla.org/en-US/docs/Web/HTTP/Status

https://www.w3schools.com/xml/xml_soap.asp

https://study.com/academy/lesson/what-is-xsd-examples-tutorial.html

bottom of page