What Is an API?

An API — Application Programming Interface — is the contract between a producer of capability and the consumers who use it. Every modern application is built from many such contracts: the database driver, the cloud SDK, the payment gateway, your own internal services, and the public surface other teams or customers integrate against.

Why Design Matters

Code is easy to change. APIs are hard. Once a public API has callers, every breaking change is a coordinated migration. That is why a thoughtful API at design time saves years of pain.

• Stability — clients depend on shapes, names, and behaviour.
• Clarity — the wrong-looking call should look wrong; the right-looking call should be right.
• Consistency — predictable patterns reduce surprise and documentation load.
• Evolvability — additive changes must not require client edits.

API Styles You Will Meet

What Makes an API Good?

1. Predictable — once you understand one resource, the rest follow.
2. Self-describing — names, status codes, and errors carry meaning.
3. Minimal surprise — defaults are sane; magic is rare.
4. Documented — examples first, references second.
5. Backwards compatible — additive evolution wherever possible.
6. Secure by default — authentication, authorisation, and rate limits are not opt-in.

What Makes an API Bad?

• Leaks database schemas or internal class names.
• Returns 200 OK with {"error": "..."} in the body.
• Mixes verbs and nouns inconsistently (/getUser, /users/list, /user/:id).
• Uses query parameters where headers belong, or vice versa.
• Lacks pagination, so a list grows until it timeouts.
• Has no versioning strategy — every change is a breaking change.

Producers and Consumers

An API has two audiences: the team that builds and runs it, and the developers who integrate against it. The first cares about implementation, performance, and operations. The second cares about clarity, examples, and predictability. Great APIs serve both, but when they conflict, the consumer wins — because there is exactly one of you and many of them.

The Cost of Bad Decisions

A poorly designed API quickly accumulates:

• Workarounds in client code, hardcoded for life.
• Documentation drift as edge cases are discovered.
• "v2" rewrites that never fully replace v1.
• Support tickets that are really design defects in disguise.

What This Course Covers

By the end of these ten lessons you will be able to:

• Use HTTP correctly — methods, status codes, headers, content negotiation.
• Model resources for REST, including nested relationships and bulk operations.
• Build a GraphQL schema and reason about its trade-offs versus REST.
• Authenticate and authorise APIs with the right mechanism for the job.
• Add rate limits, caching, and pagination without surprising your callers.
• Version and deprecate gracefully.
• Document your API so a new developer can integrate in an afternoon.

Cert Mapping

The next lesson covers the HTTP foundation that every web API ultimately rests on.