# API Design Pattern Ch 2 - 3

#### ChengYing
What I learned
- API have to preserve backward compability, which highlights the importance of API design pattern.
- pagination pattern solves a commoon problem that I encountered.
- I like the way it separate pageToken (recognized by server only) and maxPageSize (control by API consumer)
- Include the units for primitives and rely on richer data types to help convey information not present in a name.

#### Jennifer

Content in Ch2
* API desgin pattern can be applied over to lots of similar sw problems.
* It’s rare that a design pattern is made to be used entirely on its own. Most often, design patterns focus on specific components rather than entire systems.

* API design patterns are sort of like adaptable blueprints for designing and structuring APIs.
* API design patterns are important because APIs are generally very “rigid” and therefore not easy to change, so design patterns help minimize the need for large structural changes.
* Throughout this book, API design patterns will have several sections, including the name and summary, suggested rules, motivation, overview, implementation, and trade-offs of using the provided pattern over custom alternatives.

#### Barney

Ch
- Think more before implementation, like "functional limitations", "increased complexity", "data consistency"
- Let’s define exactly how those look while offering a few example configurations.
- Talk about the experience of not concerning the flexibility
- APIs are generally very “rigid”, so it's best to make good use of the pattern-driven, the API will evolve gracefully as new functionality is needed.

Ch2

- Meaningful naming
- Restful API base on this design pattern

conclusion:

1. API design pattern is sort of a concept although there are some restrictions, but most of the time, it's still design according to different situations
2. The API design pattern is divided into two parts, the first is the principle, the rules we must abide by; the second is the pattern, which is not necessarily followed, but you can find the appropriate pattern according to different situations

#### Judy

- API design patterns are sort of like adaptable blueprints for designing and structuring APIs.
- API design patterns are important because APIs are generally very “rigid” and therefore not easy to change, so design patterns help minimize the need for large structural changes.
- Good names, like good APIs, are simple, expressive, and predictable.
- Include the units for primitives and rely on richer data types to help convey information not present in a name.

#### Jenny
* If we want a way to list resources and include different attributes in the response, use the name ("with") is not a good idea.
> For example, a Library API might have a way to list Book resources. If this API needed a way to list Book resources and include the Author resources responsible for that book, it may be tempting to create a new resource for this combination: Book-WithAuthor (which would then be listed by calling ListBooksWithAuthors or some- thing similar). This might seem fine at first glance, but what about when we need to list Book resources with the Publisher resources embedded? Or both Author and Publisher resources? (p.38, Prepositions)
- Question:
- Expressive vs. Simple? Should we consider expressive naming at the begining even there is concern of overdesigning? (Sometimes we might encounter term duplication when new business logic is added)
- Discussion:
- Prefer expressive for its flexibility.

### Summary
#### Chapter 2. Introduction to API Design Patterns
* API design patterns are sort of like adaptable blueprints for designing and structuring APIs.
* API design patterns are important because APIs are generally very “rigid” and therefore not easy to change, so design patterns help minimize the need for large structural changes.
* Throughout this book, API design patterns will have several sections, including the name and summary, suggested rules, motivation, overview, implementation, and trade-offs of using the provided pattern over custom alternatives.

#### Chapter 3. Design principles - Naming
* Good names, like good APIs, are simple, expressive, and predictable.
* When it comes to language, grammar, and syntax (and other arbitrary choices), often the right answer is to pick something and stick to it.
* Prepositions in names are often API smells that hint at some larger underlying design problem worth fixing.
* Remember that the context in which a name is used both imparts information and can be potentially misleading. Be aware of the context in place when choosing a name.
* Include the units for primitives and rely on richer data types to help convey information not present in a name.

### Further discussion
- Exercises
- Exercise 1
- Question
- Imagine you need to create an API for managing recurring schedules (“This event happens once per month”). A senior engineer argues that storing a value for seconds between events is sufficient for all the use cases. Another engineer thinks that the API should provide different fields for various time units (e.g., seconds, minutes, hours, days, weeks, months, years). Which design covers the correct meanings of the intended functionality and is the better choice?
- Discussion
- The context of the recurring schedule job is not clear enough to decide which design is better. (1. using seconds to calculate the time between two events 2. using time unit as fields to set the exact time or cycle of the recurring schedule job) If we can use the second design as cron job syntax, then it will be more flexible for the use cases. If the consumer is able to calculate the time diff between two events, it is also fine to apply this design to set the next job. It all depends on the consumer use cases and implementation of the API.

- Others
- Expressive vs. Simple?
- Question:
- Should we consider expressive naming at the begining even there is concern of overdesigning? (Sometimes we might encounter term duplication when new business logic is added)
- Discussion:
- Prefer expressive for its flexibility.