Session 1: Grasping the Core Concepts of API and REST

martin blake 12월 15, 2025

A conceptual diagram of a client and a server exchanging HTTP requests and responses through an API layer.

Session 1: Grasping the Core Concepts of API and REST

Quick Summary

This post is the first session of a beginner-friendly series on web APIs. We explore what an API is, what makes a Web API different, and how the architectural style called REST shapes modern API design. You will also learn to think in terms of resources instead of actions, understand the basic structure of HTTP requests and responses, and finally send a real GET request with curl.

Table of Contents

1. Key Takeaways

  • An API (Application Programming Interface) is a contract that defines how software components talk to each other.
  • A Web API is an API that lives on the web and communicates via HTTP or HTTPS.
  • REST (Representational State Transfer) is an architectural style that encourages resource-oriented design and the use of HTTP verbs such as GET, POST, PUT, and DELETE.
  • Instead of thinking in verbs like /getUserList, REST pushes you to think in resources like /users and express actions using HTTP methods.
  • Every HTTP interaction is a dialogue: a request (method, URL, headers, body) from the client and a response (status code, headers, body) from the server.
  • curl is a simple but powerful command-line tool that lets you experiment with Web APIs directly from your terminal.

2. API, Web API, and REST: Core Definitions

What is an API?

An Application Programming Interface is a set of rules that define how one piece of software can interact with another. You can think of it as a menu in a restaurant: the kitchen (implementation) is hidden, but the menu (API) tells you what you can order and how to ask for it.

APIs appear everywhere:

  • Operating system APIs that provide file or network access to applications.
  • Library APIs exposed as public methods or functions in a package.
  • Remote APIs that let services talk to each other over the network.

What is a Web API?

A Web API is simply an API that is accessible over the web, usually via HTTP or HTTPS. Clients send HTTP requests to specific endpoints (URLs), and the server responds with data, typically in JSON format.

Common examples include:

  • GitHub API for repositories, issues, and pull requests.
  • Payment provider APIs like Stripe or PayPal.
  • Social media APIs to post content or fetch user data.

What is REST?

REST stands for Representational State Transfer. It is not a protocol or a strict standard. Instead, it is a set of principles for designing networked applications, especially Web APIs. At its heart, REST promotes:

  • Resources identified by URIs (e.g., /users/42).
  • Stateless communication where each request contains all the information needed.
  • Use of HTTP methods for actions (GET, POST, PUT, DELETE, etc.).
  • Representations of resources (JSON, XML, HTML) sent back and forth between client and server.

3. Resource-Oriented Thinking

When people first design APIs, they often focus on actions:

  • /getUserList
  • /createNewUser
  • /deleteUserById

This action-oriented style quickly becomes inconsistent and hard to maintain. REST encourages a different mindset: Focus on the nouns (resources), not the verbs.

From verbs to resources

Consider the “user” domain. A RESTful, resource-oriented API might look like this:

  • GET /users – retrieve a list of users.
  • GET /users/123 – retrieve the details of the user with ID 123.
  • POST /users – create a new user.
  • PUT /users/123 – replace all details of user 123.
  • PATCH /users/123 – update only some fields of user 123.
  • DELETE /users/123 – delete user 123.

Notice how the URL stays stable (/users and /users/{id}), while the method expresses the action. This consistency makes an API easier to guess and easier to document.

Why resources matter

Thinking in terms of resources leads you to ask better design questions:

  • What are the core entities in my domain? (users, posts, comments, products…)
  • How are they related? (users have posts; posts have comments)
  • What are the identifiers for each resource? (/users/{userId}, /posts/{postId})

By answering these questions, you end up with cleaner API paths and a more stable contract between backend and frontend.

4. A First Look at Requests and Responses

HTTP Request

An HTTP request from a client typically has four main parts:

  • Method: what the client wants to do (GET, POST, PUT, DELETE…)
  • URL: which resource is being targeted (e.g., https://api.example.com/users/123)
  • Headers: metadata such as Authorization, Content-Type, Accept.
  • Body: the data sent to the server (commonly JSON) — usually present for POST or PUT requests.

HTTP Response

The server replies with a response that has:

  • Status code: a three-digit code describing the result (e.g., 200 OK, 201 Created, 400 Bad Request, 404 Not Found).
  • Headers: e.g., Content-Type: application/json, caching rules, etc.
  • Body: the actual payload, often a JSON representation of the requested resource or an error message.

Once you understand this basic request–response pattern, you can “read” any Web API call, no matter how complex. Tools like curl, Postman, or your browser's DevTools simply visualize this same interaction.

5. Code Example: Firing a GET Request with curl

Let’s send a real request using curl. For a simple and public API, we can use GitHub’s repository endpoint: 

# Example: GET a public GitHub repository with curl
curl -X GET "https://api.github.com/repos/octocat/hello-world" \
  -H "Accept: application/vnd.github.v3+json"

What this command does:

  • -X GET specifies the HTTP method (GET). In many cases, curl assumes GET by default, so this flag is optional.
  • The URL https://api.github.com/repos/octocat/hello-world points to a specific repository resource.
  • The Accept header tells GitHub which API version and format we want.

When you run this command, you should see a JSON response describing the repository: its name, owner, visibility, and more. This is a concrete example of a GET request to a Web API endpoint returning a resource representation.

6. Step-by-Step Exercise

  1. Check if curl is installed
    Open your terminal and run: 
    curl --version
    If you see version information, you are ready. If not, install it via your OS package manager.
  2. Choose a public API
    Start with a simple, unauthenticated API. You can use:
    • GitHub public API (used in this post)
    • JSONPlaceholder: https://jsonplaceholder.typicode.com/posts/1
  3. Send your first GET request
    Try: 
    curl https://jsonplaceholder.typicode.com/posts/1
    You should see a JSON object representing a single blog post.
  4. Inspect the response
    Add the -v (verbose) option to see the request and response headers: 
    curl -v https://jsonplaceholder.typicode.com/posts/1
    Watch the status line (e.g., HTTP/1.1 200 OK), headers like Content-Type, and the JSON body.
  5. Experiment with different endpoints
    Change the URL to /posts/2, /posts/3, or list resources with /posts. Try adding query parameters, for example: 
    curl "https://jsonplaceholder.typicode.com/comments?postId=1"
    Notice how the same base resource (comments) behaves differently when filtered.

7. Comparison Table: API vs Web API vs REST

The terms “API”, “Web API”, and “REST API” are often used interchangeably, but they refer to slightly different ideas. This table summarizes the differences:

Concept Short Definition Scope Typical Protocol Example
API A contract between software components defining how to interact. Any environment: libraries, OS, desktop, web, mobile. Function calls, IPC, HTTP, RPC, etc. File system API, graphics library API.
Web API An API exposed over the web via HTTP/HTTPS. Client–server communication on the internet or intranet. HTTP, HTTPS. GitHub REST API, Stripe API.
REST An architectural style for designing networked applications. Design principles for Web APIs. Usually HTTP/HTTPS. Resource-oriented endpoints, CRUD via HTTP verbs.

In practice, when people say “REST API”, they usually mean “a Web API that follows REST-style design principles”. The more consistently you apply those principles, the more predictable and maintainable your API becomes.

8. Questions and Next Ideas

To deepen your understanding of this first session, consider the following questions:

  • What are the main resources in the domain of an app you are currently working on?
  • How would you design RESTful endpoints for those resources?
  • Which parts of your current API design are action-oriented and could be refactored into resource-oriented URLs?
  • How does stateless communication influence how you design authentication and sessions?

In the next sessions, we can explore how to design full CRUD operations for a resource, how to handle authentication and authorization, and how to document REST APIs effectively using tools like OpenAPI/Swagger.

Reactions
martin blake

작성자: martin blake

댓글 쓰기

0 댓글