Understanding APIs: A JavaScript Developer's Guide

5. Consuming REST APIs with JavaScript (`Workspace`)

This section provides practical examples of how to make requests to REST APIs from JavaScript code running in the browser, primarily using the modern `Workspace` API.

Objectively, the `Workspace` API provides a flexible and Promise-based interface for making network requests (including to REST APIs).

Delving deeper into `Workspace` usage: * Basic GET Request: Calling `Workspace(url)` returns a Promise that resolves to a `Response` object. * Handling the Response: Check `response.ok` (or `response.status`) to see if the request was successful (e.g., status 200 OK). Use methods like `response.json()` (returns another Promise) to parse the response body as JSON, or `response.text()` for plain text. * Using Promises (`.then()`, `.catch()`): Chain `.then()` blocks to process the successful response and `.catch()` to handle errors (network errors or errors thrown during processing). * Using `async/await`: Provides a cleaner, more synchronous-looking syntax for working with the Promises returned by `Workspace` and `response.json()`. Use `try...catch` blocks for error handling. * Making Other Requests (POST, PUT, DELETE): Pass a second argument (an options object) to `Workspace` specifying the `method`, `headers` (e.g., `'Content-Type': 'application/json'`), and `body` (often using `JSON.stringify()` for sending JSON data).

Further considerations briefly mention the older `XMLHttpRequest` (XHR) object, which was used before `Workspace` but is more complex and less ergonomic.

The standard way to interact with REST APIs in modern browser-based JavaScript is using the `Workspace` API. It's built-in and uses Promises, making asynchronous requests easier to manage.

Basic GET Request with Promises:

const apiUrl = 'https://jsonplaceholder.typicode.com/posts/1'; // Example REST API endpoint

fetch(apiUrl)
  .then(response => {
    // Check if the request was successful (status code 200-299)
    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }
    // Parse the response body as JSON (returns another promise)
    return response.json();
  })
  .then(data => {
    // Work with the JSON data
    console.log('Data fetched:', data);
    // Example: Display title on the page
    // document.getElementById('title').textContent = data.title;
  })
  .catch(error => {
    // Handle any errors that occurred during the fetch
    console.error('Error fetching data:', error);
    // Example: Display error message on the page
    // document.getElementById('error').textContent = `Failed to load data: ${error}`;
  });

Same GET Request with `async/await`:

`async/await` provides syntactic sugar over Promises, making asynchronous code look more like synchronous code.

const apiUrlAsync = 'https://jsonplaceholder.typicode.com/posts/2'; // Another example endpoint

async function fetchData() {
  try {
    const response = await fetch(apiUrlAsync);

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }

    const data = await response.json(); // Wait for JSON parsing
    console.log('Data fetched (async/await):', data);
    // Process data here...

  } catch (error) {
    console.error('Error fetching data (async/await):', error);
    // Handle errors here...
  }
}

fetchData(); // Call the async function

Making a POST Request (Sending Data):

const postUrl = 'https://jsonplaceholder.typicode.com/posts'; // Endpoint for creating posts
const newData = {
  title: 'foo',
  body: 'bar',
  userId: 1,
};

fetch(postUrl, {
  method: 'POST', // Specify the method
  headers: {
    'Content-Type': 'application/json', // Indicate we're sending JSON
  },
  body: JSON.stringify(newData), // Convert the JS object to a JSON string
})
  .then(response => {
    if (!response.ok) {
      // Check for server-side errors (e.g., 4xx, 5xx)
      throw new Error(`HTTP error! status: ${response.status}`);
    }
     // Check if the response indicates success (e.g., status 201 Created)
     console.log('POST Response Status:', response.status);
    return response.json();
  })
  .then(data => {
    console.log('Success:', data); // Log the response from the server (often the created resource)
  })
  .catch(error => {
    console.error('Error during POST:', error);
  });

Similar options objects can be used for `PUT`, `DELETE`, `PATCH` methods by changing the `method` property and including a `body` if necessary.

*(Note: `XMLHttpRequest` (XHR) is the older way to make requests. While still supported, `Workspace` is generally preferred for new development due to its cleaner Promise-based API).*

6. Introduction to GraphQL APIs

This section provides a brief introduction to GraphQL, an alternative approach to building and consuming APIs, contrasting it with REST.

Objectively, GraphQL is a query language for APIs and a runtime for fulfilling those queries with existing data. It allows clients to ask for exactly the data they need and nothing more.

Delving deeper into key GraphQL concepts: * Single Endpoint: Unlike REST's multiple URLs for different resources, GraphQL APIs typically expose a single endpoint (usually via HTTP POST). * Query Language: Clients send structured queries specifying the exact fields and relationships they need. * Schema & Types: GraphQL APIs are strongly typed. The server defines a schema describing the available data types and their relationships. * No Over/Under-fetching: Because clients specify required data precisely, they avoid receiving unnecessary data (over-fetching) or needing multiple requests to gather related data (under-fetching), common issues with REST. * Mutations & Subscriptions: GraphQL defines specific operations for modifying data (Mutations) and receiving real-time updates (Subscriptions).

Further considerations mention that consuming GraphQL in JavaScript often involves using dedicated client libraries (like Apollo Client, Relay, or urql) that simplify query construction, caching, and state management, although basic requests can be made with `Workspace`.

GraphQL is an increasingly popular alternative to REST for API development. Developed by Facebook and now open-source, it offers a different approach focused on client data needs.

Key differences and concepts compared to REST:

• Query Language: GraphQL *is* a query language. Clients send a query specifying the exact data structure and fields they require.
• Single Endpoint: Typically, all GraphQL requests (queries for data, mutations for changes) are sent to a *single* URL endpoint (usually using HTTP POST).
• Strongly Typed Schema: GraphQL APIs are defined by a schema that describes the types of data available, their fields, and relationships. This enables powerful developer tools and validation.
• No Over-fetching or Under-fetching: The client dictates the response shape. You only get the data you explicitly ask for in the query, solving REST's common problem of endpoints returning too much or too little data for a specific UI component.
• Operations:
  • Query: Used for fetching data (read operations).
  • Mutation: Used for modifying data (create, update, delete operations).
  • Subscription: Used for real-time updates pushed from the server to the client over a persistent connection (e.g., WebSockets).

While you can technically send GraphQL queries using `Workspace` (as POST requests with the query in the body), JavaScript developers typically use specialized GraphQL client libraries (like Apollo Client, urql, Relay) which provide features like caching, state management, code generation based on the schema, and simplified handling of queries, mutations, and subscriptions.

# Example GraphQL Query (Sent in request body, often as JSON)
query GetUserDetails {
  user(id: "123") {
    id
    name
    email
    posts { # Get related posts
      title
    }
  }
}

# Example GraphQL Mutation
mutation CreatePost {
  createPost(title: "New Post Title", content: "...") {
    id # Return the ID of the newly created post
    title
  }
}

REST vs. GraphQL: Data Fetching (Conceptual)

(Placeholder: Diagram showing REST potentially needing multiple requests or getting extra data, vs GraphQL getting exact data in one request)