From c1a1f4f11fffe3fff9ce1b9124136c0ef2951caa Mon Sep 17 00:00:00 2001 From: John Gatward Date: Thu, 12 Mar 2026 13:01:29 +0000 Subject: [PATCH] finished chapter3 --- .../api_design_patterns/part2/chapter3.md | 54 ++++++++++++++++++- .../api_design_patterns/part2/chapter4.md | 3 ++ mkdocs.yml | 1 + 3 files changed, 56 insertions(+), 2 deletions(-) create mode 100644 docs/books/api_design_patterns/part2/chapter4.md diff --git a/docs/books/api_design_patterns/part2/chapter3.md b/docs/books/api_design_patterns/part2/chapter3.md index 7d243b6..e548537 100644 --- a/docs/books/api_design_patterns/part2/chapter3.md +++ b/docs/books/api_design_patterns/part2/chapter3.md @@ -22,7 +22,7 @@ It is critical that a name clearly convey the thing is it naming. - 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 +- On the other hand, names shouldn't be oversimplified | Name | Note | |------|------| @@ -35,4 +35,54 @@ It is critical that a name clearly convey the thing is it naming. - 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 +## Language, Grammar & Syntax + +Language being inherently flexible and ambiguous can be a good thing and a bad thing. + +- On the one hand, ambiguity allows us to name things to be general enough to support future work. + - Naming `image_url` rather than `jpeg_url` presents us from limiting ourselves to a single image format. +- One the other hand, when there are multiple ways to express the same thing, we often tend to use them interchangeably, which ultimately makes our naming choices unpredictable. + +### Language + +Use American English. + +### Grammar + +#### Imperative Actions + +REST standard verbs should use the imperative mood. They are all commands or orders. + +- `isValid()`: Should it return simple boolean field? Should it return a list of errors? +- `GetValidationErrors()`: Clear that it will return list of errors, empty list if is valid. + +#### Prepositions + +- If a Library API wants to list `Book` resources with the `Author`, it's tempting to name `BooksWithAuthor`. +- This falls apart when we add in all our additional resources + - We will end up with many function names to call. +- The preposition `with` is indicative of a more fundamental problem. +- Prepositions act like *code smell*, hinting at something not being quite right. + +#### Pluralisation + +- Most often, we should use the singular. +- However collection names might be pluralised. + - Use American English to pluralise. + +## Context + +- When we use `book` in the library API, we are referring to the resource, however in a flight booking API - we are referring to an action. + +This means we need to keep the context of our API in mind. + +- Context can impart additional value to a name that might otherwise lack a specific meaning. +- It can also lead us astray when we use words with a specific meaning but don't make sense without the context. + - *record* is very generic, until you consider the context of an audio recording API. + +## Data types and units + +A name can become more clear when using a richer data type. + +- `dimensions: String;` - this is ambiguous +- `dimensions: Dimensions;` (where `Dimensions` is an object) diff --git a/docs/books/api_design_patterns/part2/chapter4.md b/docs/books/api_design_patterns/part2/chapter4.md new file mode 100644 index 0000000..ecd84fe --- /dev/null +++ b/docs/books/api_design_patterns/part2/chapter4.md @@ -0,0 +1,3 @@ +# Resource Scope and Hierarchy + +Page 47 diff --git a/mkdocs.yml b/mkdocs.yml index 6b2bc6f..5280b0e 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -72,4 +72,5 @@ nav: - 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 + - Chapter 4. Resource Scope and Hierarchy: books/api_design_patterns/part2/chapter4.md