---
# System prepended metadata

title: API Design Pattern Chapter 6 - 7

---

# API Design Pattern Chapter 6 - 7

### Jon
- When a method should be idempotent or avoid side effects? Should we always follow the definition of HTTP methods?
    - It depends on the situation you face. Take counter as an example.
- Filtering
    - Take a filtering example in e-store such as PCHome.
    - When we implement the filtering mechanism, we expect consumer to call the API to filter the order via several conditions. Would this increase the number of API calls?
    - API calls cost v.s. processing cost/network bandwidth?
- What should we follow? RFC specification or the book? 
- References
    - [RFC 7231 Definition of HTTP method](https://www.rfc-editor.org/rfc/rfc7231#section-4.3.3)

### ChengYing
- What I learned at Chapter 6
    - UUID is not the best choice for ID
    - Integer is also not a good identifier
    - We could use checksum to add into ID and verify ID
- What I learned at Chapter 7
    - How to preserve idempotence and avoid side effects in API design
        - Is it a bad idea to cache the endpoint distribution status?
    - Applying ordering over a list of items is also generally discouraged.
        - How could we provide the data needed by customer if the number of matched resuls is large
    - Replace is a semi-standatd method
    - Always the best choice to try building the API using standard methods and only expanding to custom options when some unforeseen scenario makes them absolutely necessary. 
        - One console, one button seems like to be the company strategy. It is difficult to design API just doing one thing (method). 


### Barney
- CH6
    - To meet size and efficiency issue, we should choose a more dense character like Base64.
    - ID's data type would recommand to be "string".
- CH7
    - the general guideline is that each standard method should exist on each resource unless there is a particular reason
    - if delete a resource and didn't find the resource, it should return 404(data not found), but if you want to delete whole resources, what status code should return?
        - I think it should return 200(OK), because this can show that the delete action has been successfully executed, even if the target resource does not exist.
        - Plus, you can consider to use 204(No Content)
    - Why is it not recommended to calculate the count of the result? If you want to use it, it is also recommended to use the estimate count
        - I guess this type of situation should refer to a high-traffic, high-concurrency system. Maybe when you finish the calculation and send it back, the actual value changes again.



### Summary
#### Chapter 6
- Identifiers are the values used to uniquely point to specific resources in an API.
- Good identifiers are easy to use, unique, permanent, fast and easy to generate, unpredictable, readable, copyable, shareable, and informationally dense.
- From a customer’s perspective, identifiers should be strings, using the ASCII character set, ideally relying on Crockford’s Base32 serialization format.
- Identifiers should use a checksum character to distinguish between a resource that doesn’t exist and an identifier that could never point to a resource (and is likely the result of a mistake).
#### Chapter 7
- Standard methods are a tool to drive more consistency and predictability.
- It’s critical that all standard methods follow the same behavioral principles (e.g., all standard create methods should behave the same way).
- Idempotency is the characteristic whereby a method can be repeatedly called with identical results on all subsequent invocations.
- Not all standard methods must be idempotent, but they should not have side effects, where invoking the method causes changes somewhere else in the API system.
- While it might seem counterintuitive, the standard delete method should not be idempotent.
- Standard methods do force a tight fit into a very narrow set of behaviors and characteristics, but this is in exchange for a much easier-to-learn API that allows users to benefit from their existing knowledge about resource-oriented APIs.

### Further discussion
#### Jon
- When a method should be idempotent or avoid side effects? Should we always follow the definition of HTTP methods?
    - It depends on the situation you face. Take counter as an example.
- Filtering
    - Take a filtering example in e-store such as PCHome.
    - When we implement the filtering mechanism, we expect consumer to call the API to filter the order via several conditions. Would this increase the number of API calls?
    - API calls cost v.s. processing cost/network bandwidth?
- What should we follow? RFC specification or the book? 
- References
    - [RFC 7231 Definition of HTTP method](https://www.rfc-editor.org/rfc/rfc7231#section-4.3.3)

#### ChengYing
- What I learned at Chapter 6
    - UUID is not the best choice for ID
    - Integer is also not a good identifier
    - We could use checksum to add into ID and verify ID
- What I learned at Chapter 7
    - How to preserve idempotence and avoid side effects in API design
        - Is it a bad idea to cache the endpoint distribution status?
    - Applying ordering over a list of items is also generally discouraged.
        - How could we provide the data needed by customer if the number of matched resuls is large
    - Replace is a semi-standatd method
    - Always the best choice to try building the API using standard methods and only expanding to custom options when some unforeseen scenario makes them absolutely necessary. 
        - One console, one button seems like to be the company strategy. It is difficult to design API just doing one thing (method). 

#### Barney
- CH6
    - To meet size and efficiency issue, we should choose a more dense character like Base64.
    - ID's data type would recommand to be "string".
- CH7
    - the general guideline is that each standard method should exist on each resource unless there is a particular reason
    - if delete a resource and didn't find the resource, it should return 404(data not found), but if you want to delete whole resources, what status code should return?
        - I think it should return 200(OK), because this can show that the delete action has been successfully executed, even if the target resource does not exist.
        - Plus, you can consider to use 204(No Content)
    - Why is it not recommended to calculate the count of the result? If you want to use it, it is also recommended to use the estimate count
        - I guess this type of situation should refer to a high-traffic, high-concurrency system. Maybe when you finish the calculation and send it back, the actual value changes again.