From 3a49c14cfa4dae61f17908aac4534f1fb53929d9 Mon Sep 17 00:00:00 2001 From: John Gatward Date: Tue, 10 Mar 2026 12:22:47 +0000 Subject: [PATCH] Added part2 & chapter3 --- .../api_design_patterns/part1/chapter2.md | 9 ++++- .../api_design_patterns/part2/chapter3.md | 38 +++++++++++++++++++ mkdocs.yml | 3 +- 3 files changed, 48 insertions(+), 2 deletions(-) create mode 100644 docs/books/api_design_patterns/part2/chapter3.md diff --git a/docs/books/api_design_patterns/part1/chapter2.md b/docs/books/api_design_patterns/part1/chapter2.md index 81a1599..3ec182d 100644 --- a/docs/books/api_design_patterns/part1/chapter2.md +++ b/docs/books/api_design_patterns/part1/chapter2.md @@ -21,4 +21,11 @@ A **software design *pattern*** is a particular design that can be applied over - Rigid interfaces make it much more difficult to iterate toward a great design. - We are often stuck with all design decisions, both good and bad. -Page 20: 2.3.3 Overview +**Pagination Pattern**: The pagination pattern is a way of retrieving a long list of items in smaller, more manageable chunks. The pattern relies on extra fields on both the request and response. + +Moving from a non-paginated to paginated response pattern: + +Q. What happens if we don't start with the pattern? + +1. All previously written clients are expected all the data in one list - it has no way of getting subsequent pages. +2. Clients are left to think they have all the data - which can lead to incorrect conclusions. diff --git a/docs/books/api_design_patterns/part2/chapter3.md b/docs/books/api_design_patterns/part2/chapter3.md new file mode 100644 index 0000000..7d243b6 --- /dev/null +++ b/docs/books/api_design_patterns/part2/chapter3.md @@ -0,0 +1,38 @@ +# Naming + +In every software system we build, and every API we design or use - there are names that will live far longer than we ever intend them to. It is **important to choose great names**. + +## Why do names matter? + +When designing and building an API, the names we use will be seen by & interacted with all users of the API. + +## What makes a name "good"? + +### Expressive + +It is critical that a name clearly convey the thing is it naming. + +- e.g. The term topic is used in both messaging and machine learning. +- If your project includes both using the name *topic* will be confusing. +- A more **expressive** name is required: + - `topic_model` + - `topic_message` + +### Simple + +- While an expressive name is important, it can also become burdensome if the name is excessively long without adding additional clarity. +- Names should be expressive but only to the extent that each additional part of a name adds value to justify its presence. +- On the other hand, names shouldn't be oversimplifed + +| Name | Note | +|------|------| +| `UserSpecifiedPreferences` | Expressive, but not simple enough | +| `UserPreferences` | Both simple & expressive | +| `Preferences` | Too simple | + +### Predictable + +- In general, we should use the same name to represent the same thing, and different names to represent different things. +- The basic goal is to allow users of an API to learn one name and continue building on that knowledge to be able to predict what future names would look like. + +Page 36 3.3 diff --git a/mkdocs.yml b/mkdocs.yml index 1868e6a..6b2bc6f 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -70,5 +70,6 @@ nav: - Part 1. Introduction: - Chapter 1. Introduction to APIs: books/api_design_patterns/part1/chapter1.md - Chapter 2. Introduction to API Design Patterns: books/api_design_patterns/part1/chapter2.md - + - Part 2. Design Principles: + - Chapter 3. Naming: books/api_design_patterns/part2/chapter3.md