# Unit 3: Introduction to REST and IBM Database ## 3.1 Introduction to REST Architecture and API Design ### REST (Representational State Transfer) * **Definition**: An architectural style for designing networked applications. It's a set of constraints for building distributed hypermedia systems. * **Key Principles**: * **Client-Server**: Separation of concerns. Client manages UI, Server manages data and logic. * **Stateless**: Each request from client to server must contain all necessary information. Server does not store client state between requests. * **Cacheable**: Responses can be marked as cacheable or non-cacheable to improve performance. * **Uniform Interface**: Simplifies and decouples architecture. * **Resource Identification**: Resources identified by URIs (Uniform Resource Identifiers). * **Resource Manipulation through Representations**: Clients interact with resources via their representations (e.g., JSON, XML). * **Self-descriptive Messages**: Each message includes enough information to process the message. * **Hypermedia as the Engine of Application State (HATEOAS)**: Client navigates application state via hypermedia links provided by the server. * **Layered System**: Client cannot tell if it's connected directly to the end server or an intermediary. * **Code-On-Demand (Optional)**: Server can temporarily extend client functionality by transferring executable code. ### API (Application Programming Interface) Design for REST * **Resources**: Core concept. Nouns, not verbs. (e.g., `/users`, `/products`). * **HTTP Methods (Verbs)**: Standard operations on resources. * `GET`: Retrieve a resource. (Idempotent, Safe) * `POST`: Create a new resource or submit data for processing. (Not Idempotent) * `PUT`: Update an existing resource or create if it doesn't exist. (Idempotent) * `DELETE`: Remove a resource. (Idempotent) * `PATCH`: Partially update a resource. * **URIs**: Unique identifiers for resources. Use plural nouns, hierarchical structure. * Example: `/api/v1/users`, `/api/v1/users/123` * **Request/Response Headers**: Provide metadata (e.g., `Content-Type`, `Accept`). * **Status Codes**: Indicate outcome of request (e.g., `200 OK`, `201 Created`, `400 Bad Request`, `404 Not Found`, `500 Internal Server Error`). ### Best Practices for Using REST in Applications * **Use HTTP methods correctly**. * **Design for statelessness**. * **Provide clear and consistent URIs**. * **Use appropriate status codes**. * **Employ versioning (e.g., `/v1/users`)**. * **Use JSON for data representation**. * **Implement proper error handling**. * **Consider HATEOAS for discoverability**. ## 3.2 Advantages of Using JSON Format * **Lightweight**: Smaller than XML, reducing bandwidth and faster parsing. * **Human-Readable**: Easy for developers to read and write. * **Data Structure**: Supports arrays and objects, making it flexible for complex data. * **Widely Supported**: Parsers available in almost all programming languages. * **Native JavaScript Support**: Directly maps to JavaScript objects, ideal for web applications. * **Commonly Used in Web APIs**: De facto standard for RESTful APIs. **[Figure: JSON vs. XML Comparison]** This figure would visually compare a simple data structure in JSON and XML formats. It highlights JSON's conciseness and readability, which are key advantages in web API development for efficient data exchange. ## 3.3 IBM Watson Services REST APIs * **IBM Watson**: A suite of AI services (e.g., Natural Language Understanding, Speech to Text, Vision) accessible via REST APIs. * **Interaction**: Developers send HTTP requests (GET, POST) with data/parameters to specific Watson service endpoints. * **Responses**: Watson services return results, typically in **JSON** format. * **Authentication**: Usually API keys or OAuth tokens are required. * **Use Cases**: Building intelligent applications that can understand language, process images, generate speech, etc. ## 3.4 Database Types and Capabilities ### Database Categories * **Relational Databases (SQL)**: * **Structure**: Tables with rows and columns, predefined schema. * ** ACID Compliance**: Atomicity, Consistency, Isolation, Durability. * **Examples**: PostgreSQL, MySQL, Oracle, SQL Server. * **NoSQL Databases**: * **Structure**: More flexible schemas, can be document, key-value, wide-column, or graph. * **Scalability**: Designed for horizontal scaling and handling large volumes of data. * **Examples**: MongoDB, Cassandra, Redis, CouchDB. ### Capabilities * **Data Storage & Retrieval**: Core function. * **Data Integrity**: Ensuring accuracy and consistency. * **Querying**: Fetching specific data using languages (SQL) or APIs. * **Transactions**: Grouping operations to ensure all succeed or fail together. * **Scalability**: Handling increasing data load and user traffic. * **Availability**: Ensuring the database is accessible. * **Security**: Protecting data from unauthorized access. ## 3.5 Main Data Services on IBM Cloud * **IBM Cloudant**: A fully managed NoSQL JSON document database. * **IBM Db2**: A relational database, suitable for transactional workloads. * **MongoDB Atlas**: Managed MongoDB service. * **PostgreSQL**: Managed relational database service. * **Databases for Redis/etcd/Elasticsearch**: In-memory, key-value, search capabilities. ### Benefits of IBM Cloudant * **Managed Service**: No infrastructure management required. * **Global Distribution**: Data can be replicated across multiple data centers for high availability and low latency. * **Scalability**: Scales automatically to handle large datasets and traffic. * **JSON Document Store**: Flexible schema, ideal for modern, agile development. * **Offline Sync**: Built-in capabilities for data synchronization with mobile/web clients. * **High Availability**: Built on Apache CouchDB, offering fault tolerance. * **Indexing**: Supports secondary indexes for efficient querying. ## 3.6 APIs to Interact with Cloudant Database * **RESTful API**: Cloudant provides a HTTP-based API for all operations. * **Key Operations**: * **Create Document**: `POST /` with JSON document. * **Read Document**: `GET //` * **Update Document**: `PUT //` with JSON document and `rev` (revision ID). * **Delete Document**: `DELETE //?rev=` * **Query Documents**: `POST //_find` with a JSON query body (using Mango query language). * **View Documents**: `GET //_all_docs` (or using a design document view). * **Data Format**: Primarily **JSON**. * **Authentication**: API Key or IAM credentials. ## 3.7 NoSQL vs. SQL Comparison | Feature | SQL (e.g., PostgreSQL) | NoSQL (e.g., MongoDB) | | :-------------- | :--------------------------------------------------- | :-------------------------------------------------------- | | **Data Model** | Relational (Tables, Rows, Columns) | Document, Key-Value, Wide-Column, Graph (Flexible) | | **Schema** | Predefined, Strict | Dynamic, Flexible | | **Scalability** | Vertical (Scale Up) primarily; Horizontal is complex | Horizontal (Scale Out) designed for | | **ACID** | Strong ACID compliance | Often prioritizes Availability and Partition Tolerance (BASE) | | **Querying** | Structured Query Language (SQL) | Varies by type (e.g., MongoDB Query Language, APIs) | | **Use Cases** | Complex transactions, financial systems, ERPs | Big Data, real-time apps, content management, IoT | | **Data Integrity** | High, enforced by schema and constraints | Can be application-level | ### PostgreSQL (SQL) * **Strengths**: ACID compliance, complex queries, joins, data integrity. * **Weaknesses**: Can be harder to scale horizontally, rigid schema. ### MongoDB (NoSQL - Document) * **Strengths**: Flexible schema, high scalability, fast for read/write of documents, JSON-like documents. * **Weaknesses**: Less strict consistency by default, joins are less efficient. ## 3.8 API Testing with Postman/Swagger ### Postman * **Purpose**: A collaboration platform for API development and testing. * **Key Features**: * **Send HTTP Requests**: GET, POST, PUT, DELETE, etc. * **Inspect Responses**: View status codes, headers, body. * **Organize Requests**: Collections for grouping APIs. * **Environment Variables**: Manage different configurations (dev, prod). * **Automated Testing**: Write test scripts (JavaScript) to validate responses. * **Mock Servers**: Simulate API responses. **[Figure: Postman Interface Screenshot]** This figure would show a typical Postman window, highlighting areas for request URL, HTTP method selection, request body, response body, and test results. It's important for understanding how to practically interact with and test REST APIs. ### Swagger (OpenAPI Specification) * **Purpose**: A standard, language-agnostic interface description for RESTful APIs. * **Key Features**: * **API Documentation**: Describes endpoints, parameters, responses. * **Interactive Documentation**: Swagger UI provides a web interface to explore and test APIs. * **Code Generation**: Can generate server stubs and client SDKs. * **Swagger UI**: A web interface that automatically generates interactive API documentation from an OpenAPI specification. Allows users to try out API calls directly from the browser. **[Figure: Swagger UI Example]** This figure would depict the Swagger UI, showing a list of API endpoints with expandable sections for parameters, sample requests, and responses. It demonstrates how Swagger UI makes APIs discoverable and testable without writing custom code.