API FUNDAMENTALS / LESSON 03

URLs and Endpoints.

Addressing resources on the web

Written by Andrew Lee JenkinsPublished Oct 5, 202610 min readFree lesson

Every API request needs somewhere to GO. You can't mail a letter without an address, and you can't send an API request without a URL. The specific spots where you send those requests are called endpoints.

What is a URL?

Good news, you already know this one. A URL is a web address. You type them into your browser every day.

Example

https://www.google.com
https://www.weather.com/forecast
https://api.example.com/users

A URL tells your computer where to find something on the internet. Think street addresses, but for the web.

Parts of a URL

Let's pull a URL apart and look at the pieces.

Example

https://api.example.com/users/42?active=true

Step 1. Protocol: https://

This is HOW you connect. HTTPS means secure and HTTP means not secure. Go with HTTPS whenever you can.

Step 2. Domain: api.example.com

This is the server's address. It's like the street address of a building.

Step 3. Path: /users/42

This is the specific spot on that server... kinda like the apartment number inside the building.

Step 4. Query String: ?active=true

These are extra options or filters, and they show up after a question mark. Think of them as special instructions for your order.

What is an Endpoint?

An endpoint is a specific URL where an API accepts requests. Each one does its own job.

Back to the restaurant for a sec. The restaurant has one address, but inside there are a few different counters.

The order counter (where you place orders)
The pickup counter (where you get your food)
The returns counter (where you complain if something's wrong)

Each counter is like an endpoint. Same building, different purposes.

Common Endpoint Patterns

Most APIs follow pretty similar patterns for their endpoints. Learn the pattern once and you can usually guess how a brand new API works (which feels like a lil superpower the first time it happens).

Collection Endpoints

These work with lists of things.

Example

/users         - All users
/products      - All products
/orders        - All orders

Individual Endpoints

These work with one specific thing, so they include an ID.

Example

/users/42      - User number 42
/products/789  - Product number 789
/orders/123    - Order number 123

Nested Endpoints

Sometimes things belong to other things.

Example

/users/42/orders       - All orders for user 42
/products/789/reviews  - All reviews for product 789

Combining Methods and Endpoints

HTTP methods and endpoints are a team. The method says WHAT to do and the endpoint says WHERE to do it.

Here's how they team up on a user endpoint.

Method	Endpoint	What It Does
GET	/users	Get all users
GET	/users/42	Get user 42
POST	/users	Create a new user
PUT	/users/42	Update user 42
DELETE	/users/42	Delete user 42

Same endpoint pattern, different methods, different actions.

Query Parameters

Sometimes you want to filter or tweak what comes back. That's what query parameters are for. They go at the end of the URL after a question mark.

Example

/products?category=electronics
/users?page=2&limit=10
/orders?status=pending&sort=date

If you've got more than one, you separate them with &.

Common uses for query parameters

Filtering with ?status=active (only show active items)
Sorting with ?sort=price (order by price)
Pagination with ?page=2&limit=20 (get page 2, 20 items per page)
Searching with ?search=laptop (find items matching "laptop")

Real API Examples

Here's how a couple of APIs might lay out their endpoints.

A Blog API

Example

GET  /posts              - Get all blog posts
GET  /posts/15           - Get post number 15
POST /posts              - Create a new post
PUT  /posts/15           - Update post 15
DELETE /posts/15         - Delete post 15
GET  /posts/15/comments  - Get comments on post 15
POST /posts/15/comments  - Add a comment to post 15

A Store API

Example

GET  /products                    - Get all products
GET  /products?category=shoes     - Get only shoes
GET  /products/sku-123            - Get specific product
POST /cart                        - Create a shopping cart
POST /cart/items                  - Add item to cart
DELETE /cart/items/5              - Remove item from cart
POST /orders                      - Place an order
GET  /orders/789                  - Check order status

Base URLs

Real APIs have a base URL that every endpoint shares. The base URL is the domain part.

Example

Base URL: https://api.mystore.com

Full URLs:
https://api.mystore.com/products
https://api.mystore.com/products/123
https://api.mystore.com/orders

When you read API docs, you'll usually see just the endpoint part (/products) with the base URL mentioned once somewhere else. Glue them together and you've got the full address.

TL;DR

A URL is an address that tells your request where to go
An endpoint is a specific URL that an API accepts
Collection endpoints work with lists, like /users and /products
Individual endpoints include an ID, like /users/42
Query parameters filter or tweak results, like ?status=active
Methods and endpoints work together, so GET /users and POST /users do different things

What's Next?

You know where to send requests and which methods to use. Next up is the data itself. When APIs send and receive information they use a format called JSON, and that's what we're tackling next...

Loading the lesson…

Loading activities…