20 API Concepts Every Software Engineer Should Know

From endpoints to OAuth 2.0 — a practical, visual guide to the building blocks that power every modern web application.

APIs are everywhere. Every time your weather app fetches today’s forecast, or you log in with Google, or a payment goes through — an API is doing the work. But for developers just getting started, the terminology can feel like alphabet soup.

This guide breaks down all 20 essential API concepts you’ll encounter in real-world engineering, grouped into logical themes with practical examples and diagrams so you can actually see how they fit together.

The basics: endpoints, methods, Status codes and the request-response cycle

Every API interaction starts with a request and ends with a response. Understanding the three building blocks below will take you 80% of the way.

1. Endpoint

An endpoint is the address of a specific resource on a server — a URL you can call. Think of it as a door into the building, with each door leading to a different room.

# Examples of endpoints GET https://api.example.com/users 
# All users GET https://api.example.com/users/42 
# User #42 POST https://api.example.com/orders # Create an order

2. HTTP Methods

Methods tell the server what action to perform on the resource at the endpoint. There are five you’ll use constantly:

3. Status codes

Every response comes with a 3-digit code that tells you whether things went well — or what went wrong.

4. Request-Request Cycle

Security: Authentication, Authorization & OAuth 2.0

Security is where most junior developers trip up — because authentication and authorization sound the same but are completely different concepts.

5 & 6. Authentication vs. Authorization

Authentication answers: “Who are you?” — verifying identity via password, token, or biometrics.

Authorization answers: “What are you allowed to do?” — checking if that identity has permission to access the resource.

Think of a hotel: showing your ID at check-in is authentication. The key card that only opens your room (not others) is authorization.

7. Access tokens

Once a user authenticates, the server issues an access token — a signed string that proves the client’s identity for subsequent requests. The client attaches it to every API call in the Authorization header.

# Token attached to every request Authorization: 
Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

8. OAuth 2.0 — Delegated access in 4 steps

OAuth 2.0 is the standard that lets a user grant a third-party app limited access to their data — without sharing their password. It powers “Log in with Google” on virtually every website.

Performance: Rate Limiting, Throttling, Pagination & Caching

A fast, reliable API needs protection from overload — and strategies to deliver large datasets without choking. These four concepts work together.

9 & 10. Rate limiting vs. Throttling

These two are often confused. The difference is subtle but important:

Example: GitHub API allows 5,000 requests per hour. Hit the limit and you get a 429 until the window resets.

11. Pagination

Returning all 10 million users in one response would crash both server and client. Pagination splits results into pages. There are two common flavours:

12. Caching

Caching stores a response so that repeat requests don’t hit the database again. It can happen at multiple layers — the client, a CDN, or the server itself. The server signals cacheability via HTTP headers like Cache-Control: max-age=3600.

Reliability: Idempotency, Webhooks & Error Handling

13. Idempotency

An operation is idempotent if you can run it multiple times and always get the same result. This matters enormously when networks fail — you need to be able to safely retry a request without accidentally creating duplicate records or charges.

Safe to retry: *GET, `PUT*,DELETE` — same result no matter how many times you call them.

Not safe to retry by default: *POST* — each call may create a new resource. Fix this by adding an Idempotency-Key header with a unique ID per request.

14. Webhooks

Polling an API every few seconds to check for updates is wasteful. Webhooks flip the model: instead of you asking the server “anything new?”, the server calls you when something happens.

15. Error handling

Good APIs return consistent, structured errors so clients know exactly what went wrong and how to fix it. A well-designed error response includes a status code, a machine-readable error code, and a human-readable message.

Good: structured, actionable error { "error": { "code": "VALIDATION_FAILED",
"message": "Email address is not valid", "field": "email", "status": 422 } }

Architecture: REST vs GraphQL, API Gateway & Microservices

16 & 17. REST vs GraphQL

These are the two dominant approaches to building APIs. REST is older and more widespread; GraphQL is newer and more flexible for complex data needs.

18. API Versioning

APIs evolve. When you make a breaking change, you need to version your API so existing clients don’t break. The three common approaches:

19. API Gateway & Microservices

As applications grow, a monolith is split into microservices — small, independent services that each handle one responsibility (payments, notifications, user management). An API Gateway sits in front of all of them as a single entry point, handling routing, auth, rate limiting, and logging centrally.

20. Documentation: OpenAPI

OpenAPI (formerly Swagger) is the standard format for documenting REST APIs. You write a .yaml or .json spec that describes every endpoint, parameter, and response — and tools like Swagger UI auto-generate interactive documentation from it.

# Minimal OpenAPI 3.0 snippet paths: /users/{id}: get: summary: Get user by ID parameters: - name: id in: path required: true responses: '200': { description: User object } '404': { description: Not found }

Key takeaways

Here’s a quick summary of the mental model you should walk away with:

• Every API call is a request (method + endpoint + headers) and a response (status code + body).
• Authentication proves who you are; authorization controls what you can do. OAuth 2.0 handles both via access tokens.
• Rate limiting and caching protect your API from abuse and slow responses — build them in from day one.
• Idempotency makes retries safe. Always use idempotency keys on POST requests that have side effects (like charging a card).
• Use webhooks over polling whenever you need real-time updates — they’re faster and far more efficient.
• At scale, an API Gateway in front of microservices gives you a single place to manage cross-cutting concerns.
• Document your API with OpenAPI — it’s free, auto-generates UI, and makes your API professional from day one.

These 20 concepts aren’t just theory — you’ll encounter all of them within your first year of building or integrating APIs. Master them, and you’ll write more secure, more resilient, and more maintainable software.