What is an API?

API stands for Application Programming Interface. Think of it like a waiter in a restaurant:

In programming terms: an API defines rules for how one piece of software can request data or services from another. When you open a weather app, it uses an API to fetch weather data from a remote server.

What is REST?

REST = REpresentational State Transfer. It is an architectural style (not a protocol, not a library) for designing networked applications. Most modern web APIs follow REST.

REST Principles (6 Constraints)

HTTP Methods

HTTP methods tell the server what action you want to perform. These are also called HTTP verbs.

HTTP Status Codes

URL Structure

https://api.example.com/v1/employees/42?sort=name&order=asc
|_____|  |_____________| |_| |________| |_| |_______________|
scheme      host        ver  endpoint   id    query params

HTTP Headers

Headers are metadata sent with every HTTP request and response. They carry information about the request format, authentication, and more.

Request and Response Anatomy

HTTP Request

POST /api/employees HTTP/1.1
Host: api.example.com
Content-Type: application/json
Authorization: Bearer abc123token

{
  "name": "Darshan",
  "department": "Engineering",
  "salary": 50000
}

HTTP Response

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": 101,
  "name": "Darshan",
  "department": "Engineering",
  "salary": 50000,
  "message": "Employee created successfully"
}

REST vs SOAP

Idempotent Methods

Idempotent means: calling the same request multiple times produces the same result as calling it once.

JSON (JavaScript Object Notation)

JSON is a lightweight data format used to exchange data between client and server. Almost all modern APIs use JSON. It is human-readable and easy for machines to parse.

JSON Syntax Rules

• Data is in key-value pairs: "key": value
• Keys MUST be in double quotes (single quotes are INVALID)
• Values can be: string, number, boolean, null, object, array
• Objects use curly braces { }
• Arrays use square brackets [ ]
• No trailing commas allowed
• No comments allowed in JSON

{
  "name": "Darshan",
  "age": 22,
  "isEmployee": true,
  "address": null
}

[
  "Java",
  "Python",
  "JavaScript"
]

JSON Data Types

Valid vs Invalid JSON

VALID JSON

// All keys in double quotes, proper syntax
{
  "name": "Darshan",
  "age": 22,
  "skills": ["Java", "SQL"],
  "active": true
}

INVALID JSON (with reasons)

// ERROR 1: Single quotes (MUST be double quotes)
{ 'name': 'Darshan' }

// ERROR 2: Key without quotes
{ name: "Darshan" }

// ERROR 3: Trailing comma after last item
{ "name": "Darshan", }

// ERROR 4: Using undefined (not a JSON value)
{ "name": undefined }

// ERROR 5: Single value without object/array wrapper
"just a string"
// Actually this IS valid JSON! A single value is valid.

Nested JSON Objects and Arrays

{
  "employee": {
    "id": 101,
    "name": "Darshan",
    "department": {
      "name": "Engineering",
      "floor": 3
    },
    "skills": [
      { "name": "Java", "level": "intermediate" },
      { "name": "SQL", "level": "beginner" }
    ],
    "projects": ["ILP Guide", "Chat App"]
  }
}

JSON in Java

Using org.json Library (JSONObject, JSONArray)

Creating JSON from scratch

import org.json.JSONObject;
import org.json.JSONArray;

JSONObject emp = new JSONObject();
emp.put("name", "Darshan");
emp.put("age", 22);
emp.put("active", true);

JSONArray skills = new JSONArray();
skills.put("Java");
skills.put("SQL");
emp.put("skills", skills);

System.out.println(emp.toString(2)); // pretty print with indent 2

Parsing a JSON string

String jsonStr = "{\"name\":\"Darshan\",\"age\":22,\"skills\":[\"Java\",\"SQL\"]}";

JSONObject obj = new JSONObject(jsonStr);

// Get values
String name = obj.getString("name");      // "Darshan"
int age = obj.getInt("age");              // 22

// Get array
JSONArray skills = obj.getJSONArray("skills");
for (int i = 0; i < skills.length(); i++) {
    System.out.println(skills.getString(i));
}
// Output: Java
//         SQL

Accessing nested values

String json = "{\"employee\":{\"name\":\"Darshan\",\"dept\":{\"name\":\"Engg\"}}}";

JSONObject root = new JSONObject(json);
JSONObject employee = root.getJSONObject("employee");
JSONObject dept = employee.getJSONObject("dept");
String deptName = dept.getString("name");  // "Engg"

Using Jackson Library (ObjectMapper)

import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.JsonNode;

ObjectMapper mapper = new ObjectMapper();

// JSON String → Java Object
String json = "{\"name\":\"Darshan\",\"age\":22}";
Employee emp = mapper.readValue(json, Employee.class);

// Java Object → JSON String
String jsonOut = mapper.writeValueAsString(emp);

// Parse to tree (when you don't have a class)
JsonNode node = mapper.readTree(json);
String name = node.get("name").asText();  // "Darshan"

JSON Parsing — HackerRank Pattern

Complete HackerRank Template: Fetch API + Parse JSON

import java.io.*;
import java.net.*;
import org.json.*;

public class Solution {
    public static void main(String[] args) throws Exception {

        // Step 1: Build the URL
        String urlStr = "https://jsonmock.hackerrank.com/api/articles?page=1";
        URL url = new URL(urlStr);

        // Step 2: Open connection
        HttpURLConnection conn = (HttpURLConnection) url.openConnection();
        conn.setRequestMethod("GET");

        // Step 3: Read the response
        BufferedReader br = new BufferedReader(
            new InputStreamReader(conn.getInputStream())
        );
        StringBuilder sb = new StringBuilder();
        String line;
        while ((line = br.readLine()) != null) {
            sb.append(line);
        }
        br.close();

        // Step 4: Parse JSON
        JSONObject response = new JSONObject(sb.toString());

        // Step 5: Get the data array
        JSONArray data = response.getJSONArray("data");

        // Step 6: Loop through and extract fields
        for (int i = 0; i < data.length(); i++) {
            JSONObject item = data.getJSONObject(i);

            // Use optString to avoid errors on null values
            String title = item.optString("title", "");

            if (!title.isEmpty()) {
                System.out.println(title);
            }
        }
    }
}

Pagination Pattern (Multiple Pages)

int page = 1;
int totalPages = 1;

while (page <= totalPages) {
    String urlStr = "https://api.example.com/data?page=" + page;
    // ... fetch and parse (same as above) ...

    JSONObject response = new JSONObject(sb.toString());
    totalPages = response.getInt("total_pages");

    JSONArray data = response.getJSONArray("data");
    // process data...

    page++;
}

XML (eXtensible Markup Language)

XML is a markup language designed to store and transport data. Unlike HTML (which displays data), XML carries data. It was widely used before JSON took over, but is still used in SOAP APIs, configuration files (like pom.xml, web.xml), and enterprise systems.

XML vs HTML

XML Syntax

<?xml version="1.0" encoding="UTF-8"?>      <!-- Prolog/Declaration -->
<employees>                                    <!-- Root element (only ONE allowed) -->
    <employee id="101">                        <!-- Element with attribute -->
        <name>Darshan</name>                     <!-- Child element -->
        <department>Engineering</department>
        <salary>50000</salary>
    </employee>
    <employee id="102">
        <name>Priya</name>
        <department>HR</department>
        <salary>45000</salary>
    </employee>
</employees>

Well-Formed XML Rules

• Must have exactly one root element
• Every opening tag MUST have a closing tag: <name>...</name>
• Tags are case-sensitive: <Name> and <name> are different
• Elements must be properly nested: <a><b></b></a> (not <a><b></a></b>)
• Attribute values must be in quotes: id="101"
• Prolog (declaration) is optional but recommended

XML Parsing in Java

DOM Parser (Document Object Model)

Loads the entire XML into memory as a tree. Good for small files. Easy to navigate.

import javax.xml.parsers.*;
import org.w3c.dom.*;
import java.io.*;

public class XMLParser {
    public static void main(String[] args) throws Exception {

        // Step 1: Create DocumentBuilder
        DocumentBuilderFactory factory = DocumentBuilderFactory.newInstance();
        DocumentBuilder builder = factory.newDocumentBuilder();

        // Step 2: Parse XML file into Document
        Document doc = builder.parse(new File("employees.xml"));
        doc.getDocumentElement().normalize();

        // Step 3: Get all "employee" elements
        NodeList empList = doc.getElementsByTagName("employee");

        // Step 4: Loop through each employee
        for (int i = 0; i < empList.getLength(); i++) {
            Node node = empList.item(i);

            if (node.getNodeType() == Node.ELEMENT_NODE) {
                Element elem = (Element) node;

                // Get attribute
                String id = elem.getAttribute("id");

                // Get child element text
                String name = elem.getElementsByTagName("name")
                                  .item(0)
                                  .getTextContent();

                String dept = elem.getElementsByTagName("department")
                                  .item(0)
                                  .getTextContent();

                System.out.println(id + " - " + name + " - " + dept);
            }
        }
    }
}
// Output:
// 101 - Darshan - Engineering
// 102 - Priya - HR

SAX Parser (Simple API for XML)

Event-based. Reads XML sequentially, fires events (start element, end element, characters). Good for large files because it doesn't load everything into memory.

JSON vs XML Comparison

API Consumption in Java (HttpURLConnection)

Making a GET Request

import java.io.*;
import java.net.*;

URL url = new URL("https://api.example.com/users");
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
conn.setRequestMethod("GET");
conn.setRequestProperty("Accept", "application/json");

int statusCode = conn.getResponseCode();  // 200, 404, etc.

if (statusCode == 200) {
    BufferedReader br = new BufferedReader(
        new InputStreamReader(conn.getInputStream())
    );
    StringBuilder sb = new StringBuilder();
    String line;
    while ((line = br.readLine()) != null) {
        sb.append(line);
    }
    br.close();

    System.out.println(sb.toString());
} else {
    System.out.println("Error: " + statusCode);
}
conn.disconnect();

Making a POST Request

URL url = new URL("https://api.example.com/users");
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
conn.setRequestMethod("POST");
conn.setRequestProperty("Content-Type", "application/json");
conn.setDoOutput(true);  // Enable sending body

// Write JSON body
String jsonBody = "{\"name\":\"Darshan\",\"age\":22}";
OutputStream os = conn.getOutputStream();
os.write(jsonBody.getBytes());
os.flush();
os.close();

int code = conn.getResponseCode();  // Expect 201
System.out.println("Response Code: " + code);

Complete Template: Fetch + Parse + Extract

import java.io.*;
import java.net.*;
import org.json.*;

public class Solution {

    // Reusable method: fetch JSON from any URL
    static String fetchJSON(String urlStr) throws Exception {
        URL url = new URL(urlStr);
        HttpURLConnection conn = (HttpURLConnection) url.openConnection();
        conn.setRequestMethod("GET");

        BufferedReader br = new BufferedReader(
            new InputStreamReader(conn.getInputStream())
        );
        StringBuilder sb = new StringBuilder();
        String line;
        while ((line = br.readLine()) != null) {
            sb.append(line);
        }
        br.close();
        return sb.toString();
    }

    public static void main(String[] args) throws Exception {

        // Example: Get total goals by a football team in a year
        String team = "Barcelona";
        int year = 2011;
        int totalGoals = 0;

        int page = 1;
        int totalPages = 1;

        while (page <= totalPages) {
            String url = "https://jsonmock.hackerrank.com/api/football_matches"
                + "?year=" + year
                + "&team1=" + URLEncoder.encode(team, "UTF-8")
                + "&page=" + page;

            JSONObject resp = new JSONObject(fetchJSON(url));
            totalPages = resp.getInt("total_pages");

            JSONArray data = resp.getJSONArray("data");
            for (int i = 0; i < data.length(); i++) {
                JSONObject match = data.getJSONObject(i);
                totalGoals += match.getInt("team1goals");
            }
            page++;
        }

        System.out.println("Total Goals: " + totalGoals);
    }
}

Error Handling for API Calls

try {
    HttpURLConnection conn = (HttpURLConnection) url.openConnection();
    conn.setRequestMethod("GET");
    conn.setConnectTimeout(5000);  // 5 second timeout
    conn.setReadTimeout(5000);

    int code = conn.getResponseCode();

    if (code == 200) {
        // Read from getInputStream()
    } else {
        // Read error from getErrorStream()
        BufferedReader err = new BufferedReader(
            new InputStreamReader(conn.getErrorStream())
        );
        // handle error...
    }
} catch (SocketTimeoutException e) {
    System.out.println("Connection timed out");
} catch (IOException e) {
    System.out.println("Network error: " + e.getMessage());
}

Practice Questions