An API is a way for one program to ask another for data. Your app sends a request to a specific URL, and the server sends back an answer, usually as JSON. The easiest way to understand how APIs work is to make that request yourself. A weather app does this every time it shows you the forecast.
This guide walks through one hands-on task: sending a real API request and reading the reply. Four small ideas explain almost every API: endpoints, methods, JSON and status codes. You don't need coding experience. You only need a few free tools and some careful steps, and once you've done it, the apps on your phone will make a little more sense.
- An endpoint is the specific URL that returns one kind of data.
- The method is the verb: GET reads data, POST sends new data.
- Query parameters, headers and an API key add the details an API may need.
- Responses come back as a status code plus a JSON body made of keys, values, objects and arrays.
- A 200 status plus the data you asked for means success. Other codes point to the problem.
- 0:00Intro
- 0:31What You'll Achieve and Need
- 1:15Pick an Endpoint
- 2:11Choose a Method
- 3:04Add the Details It Needs
- 4:06Send the Request
- 4:50Read the JSON Response
- 5:51Verify the 200 and Data
- 6:40Fix the Common Errors
- 7:33The Whole Request in Six Points
- 8:11Ask the right URL, read the JSON
Gather the Free Tools You Need
Before sending anything, be clear about the goal: you send one request and you understand the answer that comes back. You won't write a full program to get there. The setup is short, and everything on the list is free, so you can follow along on any computer.
A browser lets you read the API's documentation, which is where most of your answers will come from. Curl, a command-line tool, or Postman, a desktop app, does the actual sending. Some APIs ask for a key so they know who is calling. Others don't. Curiosity matters more than it sounds, because poking around is how this starts to feel familiar.
- A web browser, for reading the API docs
- curl or Postman, both free tools for sending requests
- An API key, but only if your API requires one
- Curiosity, because you learn most by trying things
Pick the Right Endpoint
Step one is choosing an endpoint. An endpoint is the specific URL where an API offers one kind of data. Think of it as picking which door to knock on. Most APIs have many endpoints, and each is a full web address that answers a different question.
In our example, the app talks to api.example.com, the API's home address. From there the work splits up. /weather returns current conditions, /forecast returns the days ahead, and /cities returns place names. We'll use /weather. The key idea is one URL, one job. If you call the wrong endpoint, you'll get the wrong kind of data back, even if the request itself works perfectly.
So don't guess. Every public API publishes a list of its endpoints and what each one returns. Look up the URL there first. Choosing the right endpoint at the start saves you the most time later.
- Find the API's documentation page
- Locate the endpoint that returns the data you want
- Copy the full URL rather than typing it from memory
Choose a Method: GET or POST
Step two is deciding what kind of request you're making. This is called the method, and it works like the verb in your sentence to the API. The same endpoint can behave differently depending on the method, and for beginners, two methods cover almost everything.
GET reads data. It asks the API for something and changes nothing on the server, which suits weather, search results or lists. POST sends new data, as when you submit a form. It creates something new, and the data travels in the body of the request. Our weather request only reads data, so GET is all we need. GET is also the safest method to practise with, because reading can't break anything.
The docs decide which methods an endpoint accepts. If you use the wrong one, the API will refuse your request. Match the method to the job.
- Reading data? Use GET
- Creating something new? Use POST
- Confirm in the docs which methods the endpoint accepts
Add Parameters, Headers and an API Key
Step three is adding the details. Many APIs need a bit more information before they'll answer, in the form of query parameters, headers or an API key. Not every API needs all three. Check the docs and add only what they ask for. The example below puts the pieces together in a curl command that asks for the weather in Paris.
Query parameters are options added to the URL after a question mark. Here, city=Paris narrows the answer to one place. To add more than one parameter, join them with an ampersand. Headers are extra notes that travel with the request but aren't part of the URL. They can say which format you want back, or say who you are. In curl, you add a header with -H.
The API key works like a password that identifies you to the API. Replace the placeholder KEY with your own key, and keep it private. Don't share it in screenshots or public code.
- Query parameters go after the ?, joined with &
- Headers are added in curl with -H
- Swap the KEY placeholder for your real key
- Keep your API key private
# Query parameter goes after the ?
URL="https://api.example.com/weather?city=Paris"
# Headers and the key go with -H
curl "$URL" -H "Authorization: Bearer KEY"Send the Request and Watch the Reply
Step four is sending it. In your terminal, press Enter on the curl command, or click Send in Postman. Every API call is a short conversation. You speak once, and the server replies with two things: a status and some data.
Your laptop sends the request, GET /weather, carrying the city and your key. The weather API checks it and replies first with a status, such as 200 OK. Then comes the body, which holds the JSON data you asked for.
Postman works the same way, with buttons instead of a command. Paste the URL, add your headers in the Headers tab, and click Send. The response appears below in a few moments. Either way, you've just spoken to an API.
- curl: press Enter on the full command
- Postman: paste the URL, fill in the Headers tab, click Send
- Expect two things back: a status and a body
Read the JSON Response
Step five is reading the reply. Most APIs answer in JSON, a plain text format built from four simple pieces: keys, values, objects and arrays. It looks strange at first, but it's really a list of labels with answers. In the example below, the response opens with a curly bracket, sets city to Paris, lists tags as sunny and dry, and gives wind its own small group with a unit.
Keys and values are the basic pairs. The key is the label, like city, written in quotes and followed by a colon. The value is the answer, like Paris. Values can be text, numbers, or true and false. Objects use curly brackets to group related keys. The whole response is one object, and wind is an object nested inside it. Groups can sit inside groups.
Arrays use square brackets to hold a list of items, like the tags in this reply. Once you can spot these four pieces, you can find any value in any API's response.
- Key and value: "label": answer
- Curly brackets { } group related keys into an object
- Square brackets hold a list of items
- Objects can sit inside other objects
{
"city": "Paris",
"tags": ["sunny", "dry"],
"wind": { "unit": "km/h" }
}Verify the 200 Status and the Data
Getting a reply isn't proof that the request worked. Check two things together: the status code, and whether the data matches what you asked for. A status alone isn't enough, and data alone isn't enough either.
Here's the check for GET /weather?city=Paris. The request is sent. The status code is 200 OK, which means success. The content type is application/json, so the body really is JSON. The data shows city: Paris, which matches the request. In curl, add the -i flag to print the status line and headers above the JSON, so you can see the 200 instead of guessing. In Postman, the status code appears right next to the response, usually in green.
- Status code reads 200 OK
- Content type is application/json
- The data matches what you requested, such as city: Paris
- Use curl -i to see the status line
Fix the Common API Errors
Not every first try returns a 200. When something goes wrong, the status code tells you where to look. Codes in the 400s usually mean something in your request needs fixing. Codes in the 500s mean the problem is on the server's side.
If you're thinking "but I copied it exactly," look closely anyway. Small slips cause most errors. Often the cause is one missing letter in the URL, or a key that has expired. Many APIs also return a short JSON explanation along with the error. Read that message first, and you'll often fix the problem in seconds.
- 401 Unauthorized: check your API key
- 404 Not Found: check the URL for typos
- 400 Bad Request: check your parameters
- 500 Server Error: wait and try again
- Read the error body for clues
Key takeaways
- Pick the right endpoint for the data you want.
- GET reads data and POST sends it.
- Add parameters, headers and a key only if the API asks for them.
- Read JSON by spotting keys, values, objects and arrays.
- Look for 200 OK and the data you expected.
- If it fails, a 401 points to your key and a 404 points to your URL.
Frequently asked questions
What is an API endpoint?
An endpoint is the specific URL where an API offers one kind of data. For example, /weather might return current conditions while /forecast returns the days ahead. The API's documentation lists every endpoint and what it returns.
What is the difference between GET and POST?
GET asks the API for data and changes nothing on the server. POST sends new data to the API, creating something new, and that data travels in the request body. For reading information like weather, GET is all you need.
Do I need to know how to code to use an API?
No. Free tools like curl and Postman let you send a request and read the reply without writing a full program. You need the API's docs, a careful eye and, sometimes, an API key.
What does a 200 status code mean?
A 200 OK status means the request succeeded. Check the data as well, to make sure it matches what you asked for, such as the right city.
Why am I getting a 401 or 404 error?
A 401 Unauthorized usually means your API key is missing, wrong or expired. A 404 Not Found usually means the URL has a typo or points to an endpoint that doesn't exist. Read the error message the API returns for more detail.
Do all APIs need an API key?
No. Some APIs require a key so they know who is calling, and others don't. The documentation tells you whether yours needs one, and if it does, keep it private.
