# API Design Pattern Ch 4 - 5

### Jon
- Chapter 4
- Resource layout
- Relationships between resources doesn't have to be the same as the relationship between data entities. (i.e., Don't assume that the API schema is the same as the database schema.)
- Create resource if you need to have operation on it.
- Anti-pattern
- in-line everything
- deep hierarchies
- resources for everything
- Exercise
- Bookmarks and Folders API design
- Clarification
- Are bookmark and folder many-to-many relationship?
- Do we have any operation on folder?
- Solution
- I prefer using bookmark as a single resource if we don't have to operate on the folder. If we need the operation on folder, we can create it as a separate resource instead of hierarchy relationship.

- Chapter 5
- Data types
- Always consider the following situations when deciding what data type to use.
- Bounds (Upper bound and lower bound)
- Default value
- What the default value will be?
- Does it make sense to your context?
- Serialization
- Different languages handle the data types in different ways. (e.g., floating point arithmetic for decimal numbers.)
- Missing v.s. null
- Enumeration
- Don't use number to represent the value of enumerated string. It is confusing. Enumeration should be avoided when another type can work instead. (We can validate the input value in server side.
### Jenny
- Ch4
- Independent resources might be just a data type !!!!
- If it is possible to in-line data, we should consider it instead of interact directly.

### ChengYing
- Chapter 4
- For API schema, why 4.3.3 in-line everything is bad?
- Chapter 5
- Exercises 2
- hasTtl:bool in Message or ChatRoom resource
- Has other resource (e.g., UserPreference) to control the TTL

### Summary
#### Chapter 4
- Resource layout refers to the arrangement and relationships between resources in an API.
- While it might be tempting to connect every resource in an API, fight the urge and only store relationships if they provide important functionality to the API.
- Sometimes it makes sense to store a separate resource for a concept. Other times it's better to in-line that data and leave the concept as a data type. The decision depends on whether you need to atomically interact with that concept.
- Avoid overly deep hierarchical relationships as the y can be difficult to comprehend and manage.
#### Chapter 5
- For every value, we also need to consider both a null value and an undefined or missing value, which may or may not have the same meaning.
- Booleans are best used for flags and should be named such that a true value means the positive aspect (e.g. enableFeature rather than disableFeature)
- Numeric values should have a true numeric meaning rather than just being made up of numeric digits.
- To avoid issues with large numbers (above 32 or 64 bits) or floating point arithmetic issues, numeric values should be serialized as strings in languages that don't have appropriate native representations.
- Strings should be UTF-8 encoded, and for any string used as an identifier of any sort, normalized to Normalization Form c.
- Enumerations should generally be avoided, relying on string values instead, with validation done on the server side rather than the client side.
- Lists should be treated as atomic collections items that are individually addressable on the client side only.
- Both lists and maps should be bounded by the total number of items allowed in the collection; however, maps should further bound the sizes of both keys and values.
### Further discussion
#### Chapter 4
- When do we need a resource?
- Question:
- If we just have one operation (e.g., GET), should we create the resource? Or just in-line the data in the parent resource?
- Discussion:
- Pros and Cons
- If we use a lot of in-line data, the api response time may be too long due to the database operation. Besdies, lots of in-line data schema will cause the breaking change easily if we need to update the schema.
- The UI may rely on the different API endpoint to separate the metadata of resource and the detail information of the resource.
- If we don't have operations on the resource, then we don't need to create an API endpoint for it. It need more effort to implement and maintain the source code.
- Summary
- It is difficult to drwa a line for creating resource and using in-line data. The principle may be described as follow:
- Consider whether there is any operation use cases on the resource.
- Take maintenance and performance into consideration.
- How to represent hierarchy relationship in API design?
- Question
- What does hierarchy relationship look like in API design?
- Discussion
- We still don't know the representation of hierarchy relationship in API design. Since hte hierarchy means the containing or ownership, we think maybe the following uri can describe the hierarchy relationship.
- Example: aws_asset/{aws_account_id}/vpcs/{vpc_id}/subnets
- The vpcs and subnet belong to the aws_account_id. If we delete the aws_account_id, then all the vpcs and subnets will be deleted cascadingly.