API Design and Interface Specification
A self-study textbook covering essential theory, comparative examples, guided practice, quality review, and a capstone exercise. Central question: How do independent systems communicate through a contract without misunderstanding?
Learning Goals and Study Routine
How do independent systems communicate through a contract without misunderstanding? You complete today’s lesson when you can answer this question in your own words, produce the required artifact, and review its quality.
Design resource-oriented URLs.
Select appropriate HTTP methods and status codes.
Distinguish safety from idempotency.
Specify request, response, and error schemas.
Explain the boundary between authentication and authorization.
Design versioning, pagination, and compatibility policies.
Recommended self-study routine
- Explain why a problem occurs before memorizing its terminology.
- Describe the difference between good and poor examples using observable criteria.
- Attempt the capstone before opening the model answer.
- Mark missing conditions in a second color and revise your artifact.
Table of Contents
- Study Guide and Learning GoalsPage 02
- Chapter 1. Core Theory and Design PrinciplesPage 04
- Chapter 2. Guided Design PracticePage 05
- Chapter 3. Case Review and Quality CheckPage 06
- Chapter 4. Capstone and Model AnswerPage 07
- Glossary and Final ChecklistPage 08
- Self-study reference and guided practicePages 09–11
Submit the capstone artifact, score at least 80/100 on the self-review, and write your own answers to the four concept questions.
Core Theory: API Design and Interface Specification
Each technical term exists to solve a recurring design problem. Study when and why the concept is needed, not merely its definition.
| Core concept | Working definition |
|---|---|
| Resource | A business object identified and manipulated through the API. |
| HTTP Method | The intent to read, create, replace, partially update, or delete. |
| Status Code | A machine-readable and human-readable processing outcome. |
| Idempotency | The property that repeated execution produces the same final state. |
| Schema | A definition of fields, types, required values, and constraints. |
| Authorization | The decision that an authenticated principal may access a resource. |
Poor and Effective Approaches
Avoid
Put creation, lookup, and cancellation behind one POST /doReservation endpoint.
Prefer
Use POST /reservations to create, GET /reservations/{id} to retrieve, and a clear cancellation resource or state transition.
[HTTP Method] [Resource URL] + [Authentication] + [Request Schema] → [Status] + [Response/Error Schema]
A Six-Step Design Workflow
Define the problem
Translate use cases into resources and state changes.
Extract the structure
Use nouns and resource hierarchy for URLs.
Design the core flow
Assign methods and specific success and failure status codes.
Add failure conditions
Define types, required fields, ranges, and examples.
Connect policies
Add ownership and role-based authorization rules.
Verify and trace
Review retries, idempotency keys, pagination, and version policy.
Worked Example
Questions for reading the example
- Are the input and initiating condition explicit?
- Are success and failure outcomes observable?
- Are duplication, authorization, concurrency, and dependency failure covered as needed?
- Can the result be traced back to a requirement?
Concept Check and Quality Review
- How do PUT and PATCH differ?
- When should an API return 401 versus 403?
- Why must errors not expose an internal stack trace?
- What are the tradeoffs of URL-based API versions?
Answer each in two or three sentences and add one example that supports your explanation.
Self-Assessment · 100 points
| Area | Standard | Points |
|---|---|---|
| Accuracy | Concepts and technical choices match the facts and requirements. | 25 |
| Completeness | Normal flow, boundaries, failures, and recovery are covered. | 25 |
| Consistency | Terms, IDs, states, and interfaces agree across artifacts. | 20 |
| Verifiability | Observable outcomes and completion criteria are present. | 20 |
| Reasoning | The choice and its tradeoffs can be explained clearly. | 10 |
Do not only correct the result. Record which question you failed to ask so your next design process prevents the same omission.
Capstone Exercise and Model Answer
Design APIs to create, retrieve, and cancel an order. Include duplicate-order prevention and protection against reading another user’s order.
- List assumptions and unresolved decisions first.
- Produce the main design as a table, diagram, or code block.
- Include the normal flow and at least three failures or boundaries.
- Score it with the rubric and compare before and after revision.
Open the model answer
POST /orders should accept an Idempotency-Key and return 201. GET /orders/{id} must allow only the owner or an administrator. Cancellation can be modeled as POST /orders/{id}/cancellations; return 409 when shipment has already started.
How to use the answer
The model is not the only valid design. If yours differs, explain the requirement, cost, complexity, or risk that justifies your choice.
Glossary and Final Checklist
| Term | Plain-English meaning |
|---|---|
| Safe Method | A method not intended to change server state. |
| Idempotent | A repeated call whose final state remains the same. |
| Pagination | Dividing a large collection into pages. |
| Rate Limit | A policy that restricts request volume over time. |
| OpenAPI | A standard for describing HTTP API contracts. |
| Backward Compatibility | Avoiding changes that break existing clients. |
Eight checks before submission
- Can you answer today’s central question in your own words?
- Are inputs, conditions, and results explicit?
- Did you include failures and recovery, not only the happy path?
- Did you review concurrency, duplicate requests, and permissions?
- Did you account for dependency failure and timeouts?
- Can you explain the disadvantages and alternatives to your choice?
- Are terminology and states consistent across artifacts?
- Is there an observable or testable completion standard?
How do independent systems communicate through a contract without misunderstanding? Answer it now using evidence from the artifact you created.
Key Terms in Context
Learn each term as a decision tool. Read across each row: definition, reason to use it, and the failure it prevents.
| Term | Plain definition | Why it matters | Example or caution |
|---|---|---|---|
| Resource | A business object identified and manipulated through the API. | It keeps URLs noun-oriented and predictable. | Use a consistent path such as `/orders/{id}`. |
| HTTP method | The verb that communicates read, create, replace, update, or delete intent. | It gives clients and servers a shared contract. | Do not mix the meanings of GET, POST, PUT, PATCH, and DELETE. |
| Status code | A numeric, machine-readable outcome of a request. | It separates success, client errors, and server errors. | Do not return 500 for ordinary validation failure. |
| Request/response schema | The fields, types, requirements, and constraints of a payload. | It is the frontend-backend contract. | Specify ranges and nullability, not only an example. |
| Pagination | A rule for retrieving a large collection in smaller parts. | It controls payload size and latency. | Offset and cursor approaches have different ordering guarantees. |
| Versioning | A policy for separating incompatible API changes. | It protects existing clients from sudden failure. | Announce deprecation and provide a migration window. |
A mobile app lists, creates, and cancels orders while handling stockouts, expired authentication, and duplicate submissions.
Guided Practice and Troubleshooting
Practice scenario
A mobile app lists, creates, and cancels orders while handling stockouts, expired authentication, and duplicate submissions.
Complete in order
- Translate each user action into a resource and HTTP method.
- Specify inputs, success responses, and error responses for every endpoint.
- Define authentication, authorization, validation, and idempotency.
- Compare OpenAPI examples with real server responses in contract tests.
Save one artifact, three assumptions, and at least three failure cases. A classmate should be able to reproduce your reasoning without asking what you meant.
If the result is wrong, diagnose it
| Observed symptom | Likely cause | Next action |
|---|---|---|
| Frontend misreads a field | Type or nullability is unspecified | Provide a schema and representative examples |
| Retry creates duplicate orders | POST has no idempotency policy | Support an Idempotency-Key |
| Every screen handles errors differently | No error code standard | Standardize code, message, and details |
Check Your Understanding
Retrieval check — answer before opening
How do PUT and PATCH differ?
PUT usually replaces a full representation; PATCH changes selected fields.
How do 401 and 403 differ?
401 means authentication is required or failed; 403 means the authenticated caller lacks permission.
When is an API spec complete?
Independent teams can implement and verify success and failure cases without guessing.
Explain the day's main decision, one failure mode, and one verification method without reading the page. If you cannot connect all three, return to the row or diagnostic case you missed.