REST API Fundamentals · Lesson 1 of 30
What Is a REST API? Web Services Explained
Every modern app is a conversation between programs. Your banking app asks the bank's servers for your balance; a shop's checkout asks a payment gateway to charge a card; Salesforce asks an ERP system for an invoice. The agreed way one program asks another for data or actions is an API (Application Programming Interface). When that conversation happens over the web, it's a web service – and today, the most common style of web service by far is REST.
In this lesson
- APIs, web services and REST in plain words
- Resources, URLs and representations
- A real REST request and response
- REST vs SOAP vs GraphQL vs gRPC
APIs and web services
A web service call
- Clienta mobile app, a website, another server, a Salesforce org
- Request over HTTP"GET /api/courses/react" – what you want, plus headers
- Serverchecks who's asking, reads the database, applies business rules
- Responsea status code (200 OK) and data, usually JSON
A website returns HTML for people to read in a browser. A web service returns data – usually JSON – for programs to use. Both travel over the same HTTP protocol, which is why you can even open a simple GET endpoint in your browser and see the JSON.
What makes it REST
REST (Representational State Transfer) is an architectural style described by Roy Fielding in 2000. Its central idea is simple:
- Everything the API exposes is a resource – a course, a student, an order – identified by a URL:
/api/courses/react. - Clients work with resources using the standard HTTP methods:
GETto read,POSTto create,PUT/PATCHto update,DELETEto remove. - The server sends a representation of the resource – a JSON document describing its current state – plus a status code that says how it went.
- Each request carries everything the server needs; the server doesn't remember previous requests (stateless).
A real REST API, running
Here's a tiny but complete REST API in Node.js with Express. You'll build much bigger ones later in this course; for now, focus on the conversation:
// server.js
import express from 'express';
const app = express();
const courses = [
{ id: 'react', title: 'React.js', lessons: 31 },
{ id: 'rest-api', title: 'REST API & Web Services', lessons: 30 },
];
// GET a collection of resources
app.get('/api/courses', (req, res) => {
res.json(courses);
});
// GET one resource by its id
app.get('/api/courses/:id', (req, res) => {
const course = courses.find((c) => c.id === req.params.id);
if (!course) return res.status(404).json({ error: `Course '${req.params.id}' not found` });
res.json(course);
});
app.listen(process.env.PORT ?? 3000, () => console.log('API listening'));
curl http://localhost:3000/api/courses/react
curl http://localhost:3000/api/courses/java
$ curl http://localhost:3000/api/courses/react
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"id": "react",
"title": "React.js",
"lessons": 31
}
$ curl http://localhost:3000/api/courses/java
HTTP/1.1 404 Not Found
Content-Type: application/json; charset=utf-8
{
"error": "Course 'java' not found"
}Two requests, two very different answers – and each one is fully described by the status line (200 OK or 404 Not Found), the Content-Type header and the JSON body. Any client in any language can understand that, which is the whole point.
REST vs SOAP vs GraphQL vs gRPC
| REST | SOAP | GraphQL | gRPC | |
|---|---|---|---|---|
| Style | resources + HTTP methods | operations in XML envelopes | one endpoint, client writes a query | remote procedure calls |
| Data format | usually JSON | XML only | JSON | Protocol Buffers (binary) |
| Contract | OpenAPI (optional) | WSDL (required) | schema (required) | .proto files (required) |
| Caching | built into HTTP | hard | hard (mostly POST) | custom |
| Typical use | public and internal web APIs | banking, legacy enterprise, Salesforce SOAP API | apps that need flexible queries | fast service-to-service calls |
Why REST won
REST reuses what the web already has – URLs, HTTP methods, status codes, caching, proxies, browsers – so it's easy to call from anywhere and easy to debug with tools like curl. Stripe, GitHub, Razorpay, Twilio and Salesforce all offer REST APIs. GraphQL and gRPC are excellent for specific needs, but REST is the default every developer is expected to know.
Practice
Try it yourself
Add a
GET /api/healthendpoint that returns{ "status": "ok" }, and call it.Show solution
// server.js import express from 'express'; const app = express(); app.get('/api/health', (req, res) => { res.json({ status: 'ok' }); }); app.listen(process.env.PORT ?? 3000);$ curl http://localhost:3000/api/health HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8 { "status": "ok" }
Quick check
What is a resource in REST?
Anything the API exposes – a course, an order, a user – identified by a URL.
What does "stateless" mean?
Each request contains everything needed; the server doesn't rely on memory of earlier requests.
Which API style uses WSDL and XML envelopes?
SOAP.
Summary
- An API lets programs talk; a web service does it over HTTP; REST is the most common style.
- REST exposes resources at URLs, manipulated with HTTP methods, returning representations and status codes.
- REST is simple, cacheable and universal; SOAP, GraphQL and gRPC fit more specific needs.
Finished this lesson?
Mark it complete to track your progress, then carry on with the next lesson.