What an API is and why you would build one
An API (Application Programming Interface) is a set of rules that lets one program talk to another. When you build an API, you are creating a way for other software — or other people's software — to request information from your program and get a response back.
Think of it like a restaurant menu. Your program is the kitchen. The API is the menu and the ordering system. Someone else's program is the customer. They look at your menu (the API documentation), place an order (make a request), and the kitchen sends back food (the response). Without the menu and ordering system, the customer would have to walk into the kitchen and figure out how to cook themselves.
You build an API when you want other developers to use your data or features without giving them direct access to your code. A weather service builds an API so that weather apps can request today's forecast. A payment processor builds an API so that online stores can process credit cards. A social media platform builds an API so that third-party tools can read or post content.
Key Takeaways
- An API is a structured way for one program to ask another program for data or to perform an action, using HTTP requests and responses in a format like JSON.
- The most common type for beginners is a REST API, which uses standard web addresses (URLs) and HTTP methods (GET, POST, PUT, DELETE) to organize requests.
- You need a server (a program that runs all the time and listens for requests), a way to handle those requests, and a database or data source to pull information from.
- Testing your API with tools like Postman or curl lets you see what your API actually returns before you hand it to other developers.
- Documentation that shows other developers what requests they can make, what data they will get back, and what errors might happen is as important as the API code itself.
REST APIs: The most common type to start with
A REST API (Representational State Transfer) is the standard way most people build APIs today. It uses the same web technology your browser uses — HTTP requests and responses — but instead of returning a web page, it returns data.
In a REST API, you organize your requests around resources — things like users, posts, products, or comments. Each resource has a web address (called an endpoint). For example, if you are building an API for a bookstore, you might have an endpoint like https://api.bookstore.com/books to get a list of all books, or https://api.bookstore.com/books/42 to get the book with ID 42.
You then use HTTP methods to say what you want to do with that resource. GET means "give me this data". POST means "create a new one". PUT means "change this one". DELETE means "remove this one". So a request to GET https://api.bookstore.com/books/42 asks for book 42. A request to POST to https://api.bookstore.com/books with book details creates a new book.
The three pieces you need to build
Every API needs three things: a server, request handlers, and a data source.
The server is a program that runs all the time and listens for incoming requests. It does not have to be a big machine in a data center — you can run one on your own computer while you are learning. Popular choices for building servers include Node.js with Express (JavaScript), Flask or Django (Python), or Go. Each one is a framework that handles the boring parts of listening for requests and sending responses back.
The request handlers are the code that decides what to do when someone makes a request. When a request comes in to GET /books/42, a handler looks up book 42 in your database, formats it as JSON (a standard text format for data), and sends it back. You write one handler for each endpoint and HTTP method combination.
The data source is where your information lives. This is usually a database like PostgreSQL, MySQL, or MongoDB. When a request comes in, your handler queries the database, gets the data, and returns it. You could also pull data from a file, another API, or anywhere else — the important part is that your handler knows how to get it.
Building a simple API step by step
Here is a concrete example using Node.js and Express, which is one of the fastest ways to get your free guide. You will need Node.js installed on your computer first.
First, create a folder for your project and open a terminal in that folder. Run npm init -y to create a package file, then npm install express to add the Express framework.
Create a file called server.js and write this code:
const express = require('express'); const app = express(); app.get('/books', (req, res) => { const books = [ { id: 1, title: 'The Hobbit', author: 'Tolkien' }, { id: 2, title: '1984', author: 'Orwell' } ]; res.json(books); }); app.listen(3000, () => { console.log('API running on http://localhost:3000'); });
This code creates a server that listens on port 3000. When someone makes a GET request to /books, it returns a list of two books as JSON. Run node server.js in your terminal, then visit http://localhost:3000/books in your browser. You will see the books printed as JSON.
That is the core of an API. From here, you would add more endpoints (like /books/1 to get a single book), connect to a real database instead of hardcoding data, add POST and DELETE handlers, and add error handling for when things go wrong.
Testing your API before you share it
Before other developers use your API, you need to test that it actually works. The easiest tool for this is Postman, a free application that lets you make requests to your API and see the responses.
Download Postman from postman.com. Open it and create a new request. Set the method to GET, paste http://localhost:3000/books into the URL field, and click Send. You will see the JSON response appear below. This is exactly what another program would receive if it made the same request.
Test each endpoint you build. Try GET, POST, PUT, and DELETE requests. Try requests with bad data or missing information — does your API return a helpful error message, or does it crash? Try requesting something that does not exist — does it return a 404 error (not found) or something else? The goal is to find problems before you hand your API to someone else.
If you prefer the command line, curl is a tool built into most computers that does the same thing. The command curl http://localhost:3000/books makes a GET request and prints the response.
Documentation: How to tell other developers what your API does
An API without documentation is useless. Other developers will not know what endpoints exist, what data to send, what they will get back, or what errors might happen. You need to write this down.
At minimum, your documentation should list each endpoint, say what HTTP method it uses, describe what data it expects (if any), show an example of what it returns, and list the possible error codes. For the bookstore example, it might look like this:
| Endpoint | Method | What it does | Returns |
|---|---|---|---|
| /books | GET | Get all books | Array of book objects |
| /books/:id | GET | Get one book by ID | Single book object or 404 error |
| /books | POST | Create a new book | The new book object with an ID |
You can write documentation in a text file, on a wiki, or use a tool like Swagger (now called OpenAPI) that generates interactive documentation automatically. Swagger reads your code and creates a page where other developers can see your endpoints and even test them in their browser.
Common mistakes and how to avoid them
The most common mistake is not thinking about security. If your API returns sensitive data, you need to make sure only authorized people can request it. This usually means requiring an API key — a secret string that the other developer includes with every request. You check that the key is valid before you send back the data. Never put an API key in your code on GitHub or anywhere public.
The second mistake is not handling errors well. If someone requests a book that does not exist, your API should return a 404 status code and a message saying "Book not found", not crash or return an empty response. If someone sends bad data, return a 400 status code and explain what was wrong. Other developers need to know what went wrong so they can fix their code.
The third mistake is changing your API without warning. If you remove an endpoint or change what it returns, any program using your API will break. If you need to make big changes, create a new version (like /v2/books) and keep the old one working for a while so people have time to update their code.
Frequently Asked Questions
Do I need a database to build an API?
Not to start. You can hardcode data in your code or read from a file, like the bookstore example above. But as soon as you want to store data that changes — like user accounts or new posts — you need a database. PostgreSQL and MySQL are popular for traditional data. MongoDB is popular for storing JSON directly.
What is the difference between REST and other types of APIs?
REST is the most common and easiest to learn. GraphQL is another type that lets the person requesting data ask for exactly what they want instead of getting a fixed response. SOAP is older and more complex. For your first API, REST is the right choice.
How do I make my API available on the internet instead of just my computer?
You need to host it on a server that runs all the time. Services like Heroku, AWS, DigitalOcean, or Render let you upload your code and they run it on their servers. Your API gets a public web address that anyone can request. Most have a free tier for learning.
What does status code 200, 404, or 500 mean?
Status codes tell the other program whether the request worked. 200 means success. 404 means not found. 400 means bad request (the data was wrong). 500 means your server crashed. Always return the right status code so the other program knows what happened.
Can I build an API with a language other than JavaScript?
Yes. Python with Flask or Django, Go, Java, C#, Ruby, and PHP all have frameworks for building APIs. The concepts are the same — you listen for requests, handle them, and send back data. Pick the language you already know or want to learn.