Forem: Chandra

API Fundamentals

Chandra — Sun, 25 Aug 2024 11:42:18 +0000

Client-Server
the client-server model is where the client (like a web browser or app) asks the server for something, like data or actions. The server processes the request and sends back what the client needs.
Stateless vs Stateful
- In a stateless API, each request from the client to the server must contain all the information needed to understand and process the request. The server does not retain any state or context between requests.
- In a stateful API, the server retains information about the client's state between requests. This means that the server can remember and use context from previous interactions. Ex: session-based authentication
REST vs RPC vs GraphQL
- REST are resource based identified by URLs and use standard HTTP method like (GET,POST,DELETE) to operate on resources
- RPC is a protocol that allows a client to execute procedures or functions on a remote server as if they were local calls.
- GraphQL is a data query and manipulation language for APIs, that allows a client to specify what data it needs.

API Versioning

url           : http://example.com/api/v1/users
query param   : http://example.com/api/users?version=1
header        : GET /api/users X-API-Version: 1
accept header : Accept: application/vnd.example.v1+json

Semantic Versioning

MAJOR Version  : 1.0.0 to 2.0.0
MINOR Version  : 1.1.0 to 1.2.0
PATCH Version  : 1.1.1 to 1.1.2
Pre-release    : 1.0.0-alpha to 2.1.0-beta.1
Build metadata : 1.0.0+build5678

OpenAPI (swagger)
- OpenAPI is a specification for defining and documenting RESTful APIs.
- OpenAPI uses a standardized format (usually written in YAML or JSON) to describe APIs
- Tools : Swagger UI, Swagger codegen, OpenAPI generator

Metadata
API metadata is information about the API itself, not the data the API provides. It's like a map or guide that tells you how to use the API. Think of metadata as the labels, instructions, and rules you need to follow when using the API.

openapi: 3.0.0
info:
  title: Simple API
  description: A basic API for managing users.
  version: 1.0.0

paths:
  /users:
    get:
      summary: Get all users
      description: Retrieves a list of all users.
      responses:
        '200':
           description: A list of users
           content: application/json

Resource Identifier & Integrity check
- resource is assigned unique identifier like UUID. These identifiers often include checksums or other mechanisms to verify that the resource hasn't been altered or corrupted.
- When you download a file, it often includes checksum. After downloading, you can use this code to check if the file is the same as the original and hasn’t been changed or corrupted.
```
{
  "resource_id": "550e8400-e29b-41d4-a716-446655440000",
  "checksum": {
    "type": "SHA-256",
    "value": "772ch98fh7wcttcfc204d14e85b"
  }
}
```
-
Pagination
- Offset based pagination
  - GET /items?offset=20&limit=10
  - offset (starting point) and a limit (number of items per page)
- Cursor based pagination
  - GET /items?cursor=eyJhbGciOiJIUzI1NiIsInR5cCI6I
  - request fetches items starting from the position indicated by the cursor. Use the given cursor to fetch next item
- Page-Based Pagination
  - GET /items?page=2&limit=10
  - This request fetches items for the second page, with 10 items per page.
- Keyset-Based Pagination
  - GET /items?start_after=12345&limit=10
  - This request fetches items after the item with ID 12345.
Filtering
- query param
  - GET /items?category=electronics&price_min=100&price_max=500
  - use query param as filter when the filter criteria are optional
- path param
  - GET /items/category/electronics
- request body (for complex filter)
```
 {
   "category": "electronics",
   "price": {
      "min": 100,
      "max": 500
   }
 }
```
  -
Partial Updates & Partial Retrieve
- Partial update refers to modifying only specific fields or attributes of a resource without having to send the entire resource. PATCH method typically used for partial updates. It allows you to send only the fields you want to update.
- Partial retrieval refers to requesting only specific fields or attributes of a resource, rather than retrieving the entire resource.
```
PATCH /users/123
Content-Type: application/json

{
  "email": "newemail@example.com"
}

GET /users/123?fields=name,email
Content-Type: application/json

{
  "name": "John Doe",
  "email": "john.doe@example.com"
}
```
-
Field Mask
- Use field masking if you want to protect sensitive data like customer phone number or social security number for data privacy.
```
{
  "name": "Jane Smith",
  "ssn": "XXX-XX-6789"
}
```
  -
API Traffic Management
- Rate limiting: Restricts the number of API requests a client can make in a given period (e.g., per minute, hour, or day).
- Quota Management: Enforces limits on the amount of data or number of requests a client can consume over a longer period (e.g., monthly quotas).
- Throttling: Temporarily limits the rate at which requests are processed to prevent system overload or to manage traffic spikes.
- Load balancing: Distributes incoming API requests across multiple servers or instances to ensure even load distribution and improve reliability.
- Caching: Stores frequently accessed API responses temporarily to reduce latency and server load.
Serialization & Deserialization
Serialization refers to the process of converting data into a format that can be easily transmitted over a network or stored in a file.

Pre-Request Validation (validateOnly=true)
pre validate data to ensure data is valid before performing crititcal operation

POST /api/users?validateOnly=true HTTP/1.1
Host: example.com
Content-Type: application/json

{ 
  "username": "user1",
  "password": "pass123"
}

Long-Running Operations (LROs)
- Polling involves periodically checking the status of a long-running operation by sending repeated requests to the server.
- Waiting involves the client receiving a response immediately that indicates the operation is underway, with an estimate of when it will be completed. The client is informed to wait for completion without continuous polling.
- Pausing and Resuming allow clients to temporarily halt a long-running operation and later resume it from where it left off.
```
POST /api/operations/{operationId}/pause 

Response:
{
   "status": "paused"
}

POST 
/api/operations/{operationId}/resume

Response:
{
   "status": "resumed"
}
```
  -
Retry Mechanisms
- Retry-After Header is used in HTTP responses to indicate how long the client should wait before retrying a failed request.
- Exponential Backoff is a strategy for retrying requests where the wait time between retries increases exponentially, e.g., 1s, 2s, 4s, 8s, etc.

API Batch Operation
Batch Operations is use for handling multiple requests or operations in a single API call. This approach can help improve efficiency, reduce network overhead, and simplify the management of multiple related operations.

POST /api/batch HTTP/1.1
Host: example.com
Content-Type: application/json

{
  "operations": [
    { "method": "POST", "url": "/api/users", "body": { "name": "Alice" } },
    { "method": "PUT", "url": "/api/users/123", "body": { "name": "Bob" } },
    { "method": "DELETE", "url": "/api/users/456" }
  ]
}

Response:
[
  { "status": 201, "body": { "id": "123" } },
  { "status": 200, "body": { "name": "Bob" } },
  { "status": 204 }
]

API Purge & Soft Deletion
- Soft deletion marking a resource as deleted without actually removing it from the database. This allows the resource to be "deleted" in a logical sense but still retains it in the storage for potential recovery or auditing.
- Purge refers to the complete removal of a resource from the database. This approach deletes the resource permanently, with no way to restore it.

Digital Signature
digital signature is a cryptographic technique used to verify the authenticity and integrity of a digital message or document.

1. Set Up Key Pair
    - Generate an RSA key pair (private key and public key).
    - Save or securely store these keys for later use.

2. Sign the Data
    - Hash the Data: Create a hash of the message or document using a hashing algorithm (e.g., SHA-256).
    - Encrypt the Hash: Encrypt the hash with the private key to create the digital signature.
    - Attach Signature: Attach the digital signature to the original message or document.

3. Send the Data
    - Transmit the message along with the digital signature to the recipient.

4. Verify the Signature
    - Decrypt the Signature: Use the sender’s public key to decrypt the digital signature and obtain the original hash.
    - Hash the Received Data: Generate a new hash from the received message or document.
    - Compare Hashes: Compare the new hash with the decrypted hash. If they match, the message is verified.

Request Authentication
- Proof of Origin: Ensures the authenticity of the request sender.
- Integrity: Guarantees that the request data hasn't been tampered with.
- Prevention of Repudiation: Ensures the sender can't deny sending the request.
- OAuth: Provides a secure and standardized way for third-party apps to access user resources without sharing credentials.
- JWT: A token-based authentication method that securely transmits claims and verifies authenticity.

Java Ecosystem Overview

Chandra — Tue, 20 Aug 2024 14:24:02 +0000

Introduction
JVM (Java Virtual Machine)
- Architecture of the JVM
  - Class Loader
  - JVM Memory
    - Method Area
    - Heap
    - Stack Area
    - Program Counter (PC) Register
    - Native Method Stack
  - Execution Engine
    - Interpreter
    - Just-In-Time (JIT) Compiler
    - Garbage Collector
JRE (Java Runtime Environment)
- Key Components of the JRE
  - Execution Tasks
  - Class Libraries
  - Java Native Interface (JNI)
  - Security Manager
JDK (Java Development Kit)
- Core Features of the JDK
  - javac (Java Compiler)
  - java (Java Application Launcher)
  - jdb (Java Debugger)
  - jar (Java Archive Tool)
  - javadoc (Java Documentation Generator)
JVM vs JRE vs JDK: What's the Difference?
JDK, JRE, JVM Hierarchy

Introduction

The Java ecosystem includes all the tools, technologies, libraries, and frameworks that support the Java programming language. It covers everything needed to develop, deploy, and manage Java applications. The main components are JDK, JRE, and JVM.

JVM (Java Development Kit)

The JVM acts like a translator that allows your computer to run Java programs and other languages compiled into Java bytecode. It translates the code into something your computer's hardware can understand and execute.

Architecture of the JVM

Class Loader

Loading load
Load .class files into memory. Locates, loads, and links class files (Java bytecode) for execution.
Linking
- Verification: Checks the bytecode for errors
- Preparation: Allocates memory for static variables and initializes the memory to default values.
- Resolution: Resolves symbolic references to direct references.
Initialization
Initialization is the final step where the JVM prepares a class or interface for use. This step happens after the class has been loaded (into memory) and linked.

JVM Memory

Method Area
Stores class-level data like methods, variables, and runtime constants.
```
public class Person {
    private String name;

    public void setName(String name) {
        this.name = name;
    }
}
```
The Method Area keeps the structure of the Person class, including its methods and fields, and runtime constants.
Heap
Heap is where the runtime memory objects are allocated. The heap is shared among all threads and is where the garbage collection process occurs.
```
Person p = new Person();
```
When you create a new Person object, it is allocated on the Heap.
Stack Area
Stack area stores frames, which contain local variables, operand stacks, and references to the runtime constant pool of the class being executed. Each thread has its own stack.
```
public void someMethod() {
    int a = 10;
    int b = 20;
    int sum = a + b;
}
```
Each time someMethod is called, a new frame is pushed onto the Stack Area. This frame includes local variables (a, b, and sum), an operand stack for intermediate calculations, and a reference to the method’s class in the Runtime Constant Pool.
Program Counter (PC) Register
PC contains the address of the current JVM instruction being executed. Each thread has its own PC register.
Native Method Stack
Similar to the Java stack, but used for native methods.

Execution Engine

Interpreter
Interpreter reads and executes Java bytecode line by line, converting it to machine-level instructions.
Just-In-Time (JIT) Compiler
Converts bytecode into machine code at runtime to speed up performance.
Garbage Collector
Manages memory by identifying and freeing up memory that is no longer in use.

JRE

JRE is a software package that provides the necessary environment to run Java applications. It is designed to execute Java bytecode on a machine, making it an essential part of the "write once, run anywhere" (WORA) principle of Java.

Key Components of the JRE

Execution Tasks
The JRE facilitates the execution of Java applications by providing the JVM and the necessary libraries and resources. JRE ensures that the JVM has everything it needs to perform these tasks on any platform.
Class Libraries
JRE includes a set of standard Java class libraries, which provide reusable code for performing common tasks, like data structures, I/O, networking, concurrency, and more.
Java Native Interface (JNI)
JNI allows Java applications to interact with native code written in languages like C or C++. This feature is essential for integrating platform-specific features or using existing native libraries.

JDK (Java Development Kit)

JDK is a tools that enables developers to write, compile, debug, and run Java applications. It is a superset of JRE and includes additional tools for Java development.

Core Features of the JDK

javac (Java Compiler)
javac is use to for converting Java source code (.java files) into bytecode (.class files). This bytecode is then executed by the Java Virtual Machine (JVM).
java (Java Application Launcher)
java command launches a Java application. It loads the necessary class files, interprets the bytecode, and starts the application.
jdb (Java Debugger)
jdb is the command-line debugger for Java programs. It allows you to inspect and debug Java applications at runtime.
jar (Java Archive Tool)
jar tool packages multiple files into a single archive file, typically with a .jar extension. These JAR files are used to distribute Java applications and libraries.
javadoc (Java Documentation Generator)
javadoc generates HTML documentation from Java source code, using the special /** */ comments known as doc comments.

JVM vs JVE vs JDK, what's the difference?

Feature/Aspect	JVM	JRE	JDK
Purpose	Executes Java bytecode	Provides the environment to run Java applications	Provides tools to develop, compile, debug, and run Java applications
Includes	JVM itself, which includes class loader, bytecode verifier, and execution engine	JVM + Core libraries (like `java.lang`, `java.util`, etc.), and other runtime components	JRE + Development tools (like `javac`, `jdb`, `jar`, etc.), documentation
Components	- Class Loader - Bytecode Verifier - Execution Engine (Interpreter, JIT)	- JVM - Core Java libraries - Java Plug-in - Java Web Start	- JRE - Java Compiler (`javac`) - JAR Tool (`jar`) - Debugger (`jdb`) - Documentation Generator (`javadoc`) - Other development tools
Main Functionality	Executes Java bytecode, enabling platform independence	Provides the minimum requirements to run Java applications	Allows developers to write, compile, and debug Java code
Who Uses It?	End-users running Java applications	End-users running Java applications	Java developers writing and compiling Java applications
Installation Size	Smallest	Larger than JVM but smaller than JDK	Largest (includes JRE and development tools)
Developer Tools	No	No	Yes (includes compiler, debugger, profiler, etc.)
Required to Run Java Programs	Yes	Yes	No (but needed to create Java programs)
Platform Independence	Provides platform independence by abstracting the underlying hardware	Yes, because it includes the JVM	Yes, it includes everything from JRE
Examples of Usage	- Running any Java application (e.g., desktop applications, servers)	- Running Java applications in production or end-user environments	- Writing and compiling Java code - Packaging applications - Debugging
Availability	Part of JRE and JDK	Standalone or part of JDK	Standalone package

JDK, JRE, JVM hierarchy

JDK (Java Development Kit)
│
├── JRE (Java Runtime Environment)
│   │
│   ├── JVM (Java Virtual Machine)
│   │   ├── Class Loader
│   │   ├── Bytecode Verifier
│   │   ├── Execution Engine
│   │   │   ├── Interpreter
│   │   │   ├── Just-In-Time (JIT) Compiler
│   │   │   └── Garbage Collector
│   │   └── Runtime Libraries (core libraries like java.lang, java.util, etc.)
│   │
│   └── Java APIs (Core libraries and additional libraries)
│
├── Development Tools (like javac, jdb, jar, javadoc, etc.)
└── Documentation (API docs, guides)

Hotel reservation Schema design (PostgreSQL)

Chandra — Sun, 18 Aug 2024 07:11:07 +0000

Audit

created_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP,
deleted_at TIMESTAMPTZ NULL

For Auditing purpose we need:

created_at: The timestamp when the record is created.
updated_at: The timestamp when the record is last updated.
deleted_at: A soft delete timestamp for the record, useful for data recovery and audit trails.
TIMESTAMPTZ: use timestamptz for scalability and consistency across time zones.

User account

CREATE TABLE user_account (
    user_id UUID PRIMARY KEY,
    email VARCHAR(255) UNIQUE NOT NULL,
    full_name VARCHAR(255) NOT NULL,
    oauth_provider VARCHAR(50),
    oauth_uid VARCHAR(255),
    created_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP,
    deleted_at TIMESTAMPTZ NULL
);

user_id: A randomly generated UUID assigned when the user is authenticated (generated only at first-time login).
email: The user's email address.
full_name: The user's full name.
oauth_provider: The name of the OAuth provider (e.g., Google, Facebook).
oauth_uid: The unique ID provided by the OAuth provider.

I am using OAuth for authentication and authorization in my application to avoid the complexities and responsibilities of managing my own authentication system.

Hotel Room

CREATE TABLE room (
    room_id INT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
    room_number VARCHAR(20) NOT NULL,
    room_type VARCHAR(20) NOT NULL,
    description TEXT,
    availability_status room_availability_status DEFAULT 'AVAILABLE',
    created_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP,
    deleted_at TIMESTAMPTZ NULL
);

room_id: I am using INT as the unique identifier because I assume the number of hotel rooms will not exceed 2,147,483,647 (the maximum value for an INT in PostgreSQL).
room_number: The room number, which I expect to be no more than 10 characters (e.g., SB001).
room_type: The type of room, such as single or double.
description: A description of the room.
availability_status: An enum indicating the room's availability status (e.g., 'AVAILABLE', 'RESERVED', 'BOOKED', 'BLOCKED').

Room pricing

CREATE TABLE room_pricing (
    pricing_id INT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
    room_id INT,
    price_per_night DECIMAL(10, 2) NOT NULL,
    available_date TIMESTAMPTZ NOT NULL,
    pricing_type pricing_type,
    created_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP,
    deleted_at TIMESTAMPTZ NULL,
    FOREIGN KEY (room_id) REFERENCES room(room_id)
);

pricing_id: Using INT as the unique identifier, considering that the 2. number of pricing records related to rooms will not exceed 2,147,483,647.
room_id: Foreign key referencing the room table.
price_per_night: The price of the room per night.
pricing_type: An enum indicating the pricing type (e.g., 'STANDARD', 'DISCOUNTED', 'PREMIUM').

User order

CREATE TABLE user_order (
    order_id UUID PRIMARY KEY
    user_id UUID,
    created_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP,
    deleted_at TIMESTAMPTZ NULL,
    FOREIGN KEY (user_id) REFERENCES user_account(user_id)
);

order_id: A UUID used as a strong unique identifier.
user_id: Foreign key referencing the user_account table for the customer who made the order.

Room booking

CREATE TABLE room_booking (
    booking_id UUID PRIMARY KEY,
    order_id UUID,
    room_id INT,
    check_in_date TIMESTAMPTZ NOT NULL,
    check_out_date TIMESTAMPTZ NOT NULL,
    booking_status booking_status,
    created_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP,
    deleted_at TIMESTAMPTZ NULL, -- Soft delete column with timezone
    FOREIGN KEY (order_id) REFERENCES user_order(order_id),
    FOREIGN KEY (room_id) REFERENCES room(room_id)
);

booking_id: A UUID used as a strong unique identifier.
order_id: Foreign key referencing the user_order table.
room_id: Foreign key referencing the room table.
check_in_date: The date and time when the user checks in.
check_out_date: The date and time when the user checks out.
booking_status: An enum indicating the booking status (e.g., 'CONFIRMED', 'CANCELLED', 'CHECKED_IN', 'CHECKED_OUT').

Payment

CREATE TABLE payment (
    payment_id UUID PRIMARY KEY,
    order_id UUID NOT NULL,
    payment_reference_id VARCHAR(255) UNIQUE,
    payment_status payment_status,
    payment_date TIMESTAMPTZ,
    payment_method payment_method,
    payment_gateway VARCHAR(100),
    amount_paid DECIMAL(10, 2) NOT NULL,
    currency CHAR(3) DEFAULT 'USD',
    created_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP,
    deleted_at TIMESTAMPTZ NULL,
    FOREIGN KEY (order_id) REFERENCES user_order(order_id)
);

payment_id: A UUID used as a strong unique identifier. I am not using payment_reference_id as the primary key because it is dependent on external services.
order_id: Foreign key referencing the user_order table.
payment_reference_id: Reference ID from the payment gateway.
payment_status: The status of the payment (e.g., 'PENDING', 'COMPLETED', 'FAILED').
payment_date: The date and time of the payment transaction.
payment_method: The method of payment (e.g., 'CREDIT_CARD', 'DEBIT_CARD').
payment_gateway: The payment gateway provider.
amount_paid: The total amount paid in the transaction. currency: ISO 4217 currency code (e.g., 'USD').

Seeding data

-- Enum for Room Availability Status
CREATE TYPE room_availability_status AS ENUM ('AVAILABLE', 'RESERVED', 'BOOKED', 'BLOCKED');

-- Enum for Pricing Type
CREATE TYPE pricing_type AS ENUM ('STANDARD', 'DISCOUNTED', 'PREMIUM');

-- Enum for Booking Status
CREATE TYPE booking_status AS ENUM ('CONFIRMED', 'CANCELLED', 'CHECKED_IN', 'CHECKED_OUT');

-- Enum for Payment Status
CREATE TYPE payment_status AS ENUM ('PENDING', 'COMPLETED', 'FAILED');

-- Enum for Payment Method
CREATE TYPE payment_method AS ENUM ('CREDIT_CARD', 'DEBIT_CARD');

Indexing

-- Indexes for user_account table
CREATE INDEX idx_user_account_email ON user_account(email);

-- Indexes for room table
CREATE INDEX idx_room_room_number ON room(room_number);
CREATE INDEX idx_room_room_type ON room(room_type);
CREATE INDEX idx_room_availability_status ON room(availability_status);

-- Indexes for room_pricing table
CREATE INDEX idx_room_pricing_room_id ON room_pricing(room_id);
CREATE INDEX idx_room_pricing_available_date ON room_pricing(available_date);

-- Indexes for user_order table
CREATE INDEX idx_user_order_user_id ON user_order(user_id);

-- Indexes for room_booking table
CREATE INDEX idx_room_booking_order_id ON room_booking(order_id);
CREATE INDEX idx_room_booking_room_id ON room_booking(room_id);
CREATE INDEX idx_room_booking_check_in_date ON room_booking(check_in_date);
CREATE INDEX idx_room_booking_check_out_date ON room_booking(check_out_date);
CREATE INDEX idx_room_booking_booking_status ON room_booking(booking_status);

-- Indexes for payment table
CREATE INDEX idx_payment_order_id ON payment(order_id);
CREATE INDEX idx_payment_payment_status ON payment(payment_status);

Walkthrough

When a user logs in, a record is created in the user_account table. Admins input data for room and room_pricing, where each room can have multiple prices depending on the date (e.g., normal days or special events like Christmas).
When a user books a room, records are created in the user_order, room_booking, and payment tables. If the booking is pending, the booking_status will be NULL, room_availability_status will be RESERVED, and payment_status will be PENDING.
If the payment is successful, the payment_status will be COMPLETED, booking_status will be CONFIRMED, and room_availability_status will be BOOKED.

any feedback will be helpful :)