Skip to content

API vs Webpage — Key Differences Every Developer Must Know

DodaTech Updated 2026-06-28 2 min read

In this tutorial, you will learn about API vs Webpage. We cover key concepts, practical examples, and best practices to help you master this topic.

The fundamental difference between an API and a webpage is that APIs return structured data (JSON, XML) for programmatic consumption, while webpages return HTML rendered by browsers for human reading.

What You'll Learn

  • How to distinguish API endpoints from regular URLs
  • Why APIs and webpages use different response formats
  • When to use an API vs serving a webpage

Why It Matters

Building a modern application means knowing when to serve an HTML page and when to expose an API endpoint. Mixing them up creates confusing, hard-to-maintain systems.

flowchart LR
    A["Browser requests /users"] --> B{"Server checks\nAccept header"}
    B -->|"text/html"| C["Returns HTML page"]
    B -->|"application/json"| D["Returns JSON data"]
    C --> E["Browser renders\nhuman-readable page"]
    D --> F["Client app parses\nstructured data"]
    style B fill:#dbeafe,stroke:#2563eb

Real-World Use

When you visit https://api.github.com/users/octocat, you get JSON. When you visit https://github.com/octocat, you get an HTML page. Same server, different endpoints serving different consumers.

Code Examples

import requests

# API endpoint returns JSON
api_response = requests.get("https://api.github.com/users/octocat")
print(type(api_response.json()))  # dict

# Regular webpage returns HTML
web_response = requests.get("https://github.com/octocat")
print(web_response.text[:200])    # <!DOCTYPE html>...

Expected output:

<class 'dict'>
<!DOCTYPE html>

# Compare content types
curl -s -o /dev/null -w "%{content_type}" https://api.github.com/users/octocat
echo ""
curl -s -o /dev/null -w "%{content_type}" https://github.com/octocat

Expected output:

application/json; charset=utf-8
text/html; charset=utf-8

Common Mistakes

1. Returning HTML from an API Endpoint

APIs should return JSON/XML, not HTML. HTML requires parsing and has no structure guarantees.

2. Treating Every URL as an API

Some URLs serve human-readable pages. Check the Accept header to distinguish.

3. Building APIs That Only Work in Browsers

APIs must work for any HTTP client, not just browsers with JavaScript.

4. Ignoring Content Negotiation

The same URL can serve different formats based on the Accept header.

5. Mixing API and Web Routes

Keep /api/ paths separate from web routes for clarity and security.

Practice Questions

  1. What format do most web APIs return?
  2. How does a server know whether to return HTML or JSON?
  3. Can the same URL serve both HTML and JSON?
  4. Why is it bad to return HTML from an API endpoint?
  5. What header tells the server what format the client expects?

Answers:

  1. JSON (JavaScript Object Notation).
  2. By checking the Accept header in the request.
  3. Yes, through a technique called content negotiation.
  4. Clients would need to parse HTML to extract data, which is fragile and slow.
  5. The Accept header specifies the desired response format.

Challenge: Create a simple Flask app with one route that returns JSON when Accept: application/json and HTML when Accept: text/html.

FAQ

Can a browser display API JSON directly?

: Yes, most browsers show JSON in a readable tree view, but it's not styled like a webpage.

Is Graphql an API or a webpage?

: GraphQL is an API query language. It returns JSON data, not HTML.

Do all APIs use HTTP?

: No. APIs can use gRPC, WebSockets, Message Queues, or other protocols.

What's Next

Learn about API Protocols including HTTP, gRPC, and GraphQL, then explore REST Introduction for the most popular API style.

← Previous API Request-Response Cycle — How Data Flows Between Applications Next → API Protocols — HTTP, gRPC, and GraphQL Compared

Built by the developers of DodaTech

Doda Browser, DodaZIP & Durga Antivirus Pro

Home Browse What Is Api