What Is an API? REST, JSON and HTTP for Web Developers

Anatomy of a request and a response

Every API call is an HTTP exchange. The request names a method and a path, carries headers and sometimes a body. The response carries a status code, headers and usually a body.

POST /api/v1/enquiries HTTP/1.1
Host: example.com
Content-Type: application/json
Authorization: Bearer <token>

{"name": "Meera", "course": "web-development"}

HTTP/1.1 201 Created
Content-Type: application/json
Location: /api/v1/enquiries/314

{"id": 314, "name": "Meera", "status": "received"}

The client asked to create an enquiry, and the server confirmed with 201 Created, the URL of the new resource and a JSON copy of what it stored. JSON (JavaScript Object Notation) is plain text made of objects, arrays, strings, numbers, booleans and null, and every major language can read and write it.

HTTP methods and REST conventions

REST (Representational State Transfer) is a style rather than a strict standard. Its core idea is that URLs name resources, written as nouns, and HTTP methods describe what you want to do with them.

GET requests must never change data, because browsers, caches and crawlers repeat them freely. Putting a version such as v1 in the path lets you change the API later without breaking existing clients.

Status codes you need to know

The status code tells the client what happened before it reads the body. The first digit gives the category: 2xx means success, 3xx a redirect, 4xx a problem with the request and 5xx a problem on the server.

Calling an API from JavaScript

In the browser you call APIs with fetch. This example sends JSON and handles both success and validation errors.

const res = await fetch('/api/v1/enquiries', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ name: 'Meera', course: 'web-development' }),
});

if (res.status === 201) {
  const enquiry = await res.json();
  console.log('Saved with id', enquiry.id);
} else if (res.status === 422) {
  const { errors } = await res.json();
  console.warn(errors);
}

Our JavaScript guide shows how to attach this kind of call to a form and display the results safely on the page.

Building a simple JSON endpoint in PHP

On the server, an endpoint reads the request, validates it, does the work and returns JSON with the right status code.

<?php
declare(strict_types=1);
header('Content-Type: application/json');

$data = json_decode(file_get_contents('php://input'), true) ?? [];
$name = trim((string) ($data['name'] ?? ''));

if ($name === '') {
    http_response_code(422);
    echo json_encode(['errors' => ['name' => 'Name is required']]);
    exit;
}

$stmt = $pdo->prepare('INSERT INTO enquiries (name) VALUES (?)');
$stmt->execute([$name]);

http_response_code(201);
echo json_encode(['id' => (int) $pdo->lastInsertId(), 'name' => $name]);

The same rules from our PHP guide apply: validate input, and use prepared statements for every query. The data itself is saved in a MySQL table.

Authentication and security

• Serve every API over HTTPS so tokens and data cannot be read in transit.
• Keep secret API keys on the server. Anything in browser JavaScript is visible to every visitor, so call third-party APIs from your back end and pass on only the result.
• Use tokens or session cookies to identify users, and check permissions on every request, not only at login.
• Apply rate limits and return 429 when a client sends too many requests.
• Configure CORS headers to allow only the origins that should call your API from a browser.

APIs connect everything else on this hub, from front-end scripts to databases. To practise them as part of complete projects, explore SkillNewton's online web development training.

Common mistakes

• Returning 200 OK with an error message in the body, which forces clients to parse text to detect failures.
• Using GET requests for actions that change or delete data.
• Placing secret API keys in front-end JavaScript or committing them to a public code repository.
• Trusting data from the request body without validating its type, length and format.
• Returning raw database errors or stack traces in API responses.

Frequently asked questions