Understanding JSON APIs for React Developers

Runnable lesson · press Try it on the examples to edit and run them here.

Most React apps get their data from a server. They do not ask for web pages; they ask for data, and the server answers with JSON. This lesson explains the vocabulary so the next lessons make sense.

What is an API?

An API (Application Programming Interface) is a set of URLs, called endpoints, that a program can call to read or change data. A web API gives answers meant for programs, not people.

1
2
3
4
5

GET  https://api.example.com/products          list all products
GET  https://api.example.com/products/42       one product
POST https://api.example.com/products          create a product
PUT  https://api.example.com/products/42       replace product 42
DELETE https://api.example.com/products/42     delete product 42

Designs like this are called REST (Representational State Transfer). Not every API follows REST rules exactly, so always read the documentation of the one you use.

HTTP methods

Status codes

Every response carries a number that says how it went:

A good React app handles the failures as well as the successes. See Error States and Fetch HTTP Errors.

JSON

JSON (JavaScript Object Notation) is text that looks like JavaScript objects and arrays. It has strings in double quotes, numbers, true/false, null, arrays and objects. No comments, no undefined, no functions. Read JSON Syntax if it is new.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

function App() {
  // This is what a server would send, as a string
  const text = `{
    "products": [
      { "id": 1, "name": "Keyboard", "price": 49.5, "inStock": true },
      { "id": 2, "name": "Mouse", "price": 25, "inStock": false }
    ],
    "total": 2
  }`;

  const data = JSON.parse(text); // turn the text into objects

  return (
    <div>
      <p>{data.total} products</p>
      <ul>
        {data.products.map((p) => (
          <li key={p.id}>{p.name} - ${p.price} {p.inStock ? "" : "(out of stock)"}</li>
        ))}
      </ul>
    </div>
  );
}

With fetch, the response gives you the text and await response.json() parses it for you (JSON.parse).

A look at the headers

Besides the body, requests and responses carry headers: metadata such as Content-Type: application/json (the format) and Authorization (who is asking). When you send JSON, set Content-Type: application/json.

Who can call an API from the browser? CORS

Browsers only let a page read responses from another website if that server allows it, using headers (this is CORS, Cross-Origin Resource Sharing). If you see “blocked by CORS policy” in the console, the server must be configured to allow your site’s origin. It cannot be fixed from React code. Common solutions: the API owner enables CORS for your origin, or your own backend or a dev-server proxy calls the API for you.

How a React app uses an API

1. A component renders with an empty or loading state.
2. An effect (or an event handler, or a data library) sends the request.
3. When the response arrives, the data is stored in state.
4. The component renders again and shows the data.

The same flow is repeated in the next lessons with loading, error and empty states, search, pagination and cancelling.

Practising without a server

Playground examples cannot reach real servers, so they use two stand-ins: fetch against data: URLs (a real fetch call with a real JSON response) and small promise-based fakeApi functions with delays and failures. The code you write around them (state, effects, rendering) is identical to code that uses a real API. Only the URL changes.

Key points

• A web API exposes endpoints; you use HTTP methods and read status codes.
• JSON is the usual data format; response.json() parses it.
• CORS is enforced by the browser and fixed on the server.
• React stores API data in state and renders it, with care for failures.