A noobs guide to web APIs
Alllll riiiight lets do this one more time, my name is Ankush and I’m your friendly neighbourhood web developer, here to educate your pathetic ass a bit about web APIs, how they can be used to connect your frontend with your backend and how you can write an API using NodeJS 🫡
An API — Application Programming Interface, defines how different applications can talk to each other and exchange data through structures requests and responses
API Types?
1. Web APIs — the one we will be focusing on today
2. OS APIs — Windows APIs, Android APIs, etc
3. Library APIs — Like a python library
4. Hardware APIs — allow accessing hardware functions (embedded libraries?)
RESTful Web APIs
A RESTful Web API is one that follows the “REST” (Representational State Transfer) principles, a software architecture style that ensures scalability, simplicity, and stateless communication between servers and clients.
Common REST HTTP Methods
There are 4 common methods/requests to call REST APIs
1. GET — to get some data from the server
2. POST — to send/create some data from the server and get a response
3. PUT — to update existing data on a server
4. DELETE — to remove some data form a server
When browsing the web, GET request is used to fetch the client side content that gets rendered by the browser
API response codes
Whenever an API is called, it will always return a status code (a number) to signify the result of the request. Categorised into 1XX (informational response), 2XX (success codes), 3XX (redirects), 4XX (client errors), 5XX (server errors)
200 — OK, successful request
301 — Moved Permanently
400 — Bad Request, invalid inputs
401 — Unauthorised
404 — Not Found
500 — Internal Server Error
Lets write an API endpoint ourselves
Make sure you have NodeJS + NPM already installed and follow these steps
mkdir api-test
cd api-test
npm init -y
npm i express
touch index.jsThis will create a folder for our express API backend and create a JS file to write code in
Edit the index.js file and add this code
const express = require('express');
const app = express();
app.get('/', (req, res) => {
res.send('Hello World');
});
app.listen(3000, () => {
console.log('Server is running on port 3000');
});We have just initialised an express backend which is serving the “Hello World” string at root (/) endpoint. i.e. on sending a GET request to /, Hello World will be returned
Run this file with node index.js and open http://localhost:3000/ on any browser. It should show Hello World
Try changing the string in res.send('this one') to a simple HTML like <h1>Hi there</h1> and restart the express server (ctrl+c and node index.js again), check if something changes on the served page
But this is just for GET requests, we cannot make POST requests to this endpoint
As you can see it gives an error if we try to make a POST request to the GET endpoint we created
Lets define a POST endpoint now
// add this after defining defining the app
app.use(express.json());
// POST endpoint
app.post('/', (req, res) => {
const name = req.body.name
res.send(`Hello ${name}!`);
});restart the app and let’s try sending a post request to the server
You can use any HTTP client like Thunder Client on VSCode or Postman. I am going to use cURL coz simple
curl http://localhost:3000/ -d '{ "name": "Ankush" }'this should print the response as Hello Ankush!
BOOM! You just created a GET and POST request! A majority of web APIs are comprised of just GET and POST requests
Time to write some frontend
<html>
<body>
<input type="text" id="name" name="name" placeholder="Enter your name">
<button onclick="handleSubmit()">Submit</button>
<script>
async function handleSubmit() {
const name = document.getElementById('name').value;
const response = await fetch('/', {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({ name })
});
const data = await response.text();
document.body.innerHTML = data;
}
</script>
</body>
</html>We will serve this HTML through the GET endpoint we created earlier
app.get('/', (req, res) => {
res.send(`
<html>
<body>
<input type="text" id="name" name="name" placeholder="Enter your name">
<button onclick="handleSubmit()">Submit</button>
<script>
async function handleSubmit() {
const name = document.getElementById('name').value;
const response = await fetch('/', {
method: 'POST',
headers: {
'Content-Type': 'application/json'
},
body: JSON.stringify({ name })
});
const data = await response.text();
document.body.innerHTML = data;
}
</script>
</body>
</html>
`);
});Restart the express app and refresh localhost:3000, and try entering your name
Now if you open developer tools and go into the network tab, you can see the POST request being sent and the different data associated with it
Congrats you just sent a POST request with some data, received some data back in response and showed it on the frontend!
Final Code:
const express = require('express');
const app = express();
app.use(express.json());
// To test this endpoint using curl, you can use the following command:
// curl http://localhost:3000/
app.get('/', (req, res) => {
res.send(`
<html>
<body>
<input type="text" id="name" name="name" placeholder="Enter your name">
<button onclick="handleSubmit()">Submit</button>
<script>
async function handleSubmit() {
const name = document.getElementById('name').value;
const response = await fetch('/', {
method: 'POST',
headers: {
'Content-Type': 'application/json'
},
body: JSON.stringify({ name })
});
const data = await response.text();
document.body.innerHTML = data;
}
</script>
</body>
</html>
`);
});
// To test this endpoint using curl, you can use the following command:
// curl http://localhost:3000/ -d '{ "name": "Ankush" }'
app.post('/', (req, res) => {
const name = req.body.name;
res.send(`Hello ${name}!`);
});
app.listen(3000, () => {
console.log('Server is running on port http://localhost:3000');
});
