diff --git a/docs/books/api_design_patterns/part1/chapter1.md b/docs/books/api_design_patterns/part1/chapter1.md index 272241c..11a0afe 100644 --- a/docs/books/api_design_patterns/part1/chapter1.md +++ b/docs/books/api_design_patterns/part1/chapter1.md @@ -1,6 +1,6 @@ # Introduction to APIs -**API**: **A**pplication **P**rogramming **I**nterface +**API**: Application Programming Interface ## What are web APIs? @@ -21,11 +21,12 @@ One of the main reasons is the idea of *statefulness*. -> **Stateless**: When an API call can be made independently from all other API requests, with no additional context. -> **Statefulness**: A web API that stores context on a user from previous API requests. +> - **Stateless**: When an API call can be made independently from all other API requests, with no additional context. +> - **Statefulness**: A web API that stores context on a user from previous API requests. > For example a web API that stores a user's favourite cities and provides weather forecasts for just those has no runtime inputs but requires a state to be set by the user. Consider the following API method names: + 1. `ScheduleFlight()` 2. `GetFlightDetails()` 3. `ShowAllFlights()` @@ -39,6 +40,7 @@ Consider the following API method names: - Was it `ShowFlights()`, `ShowAllFlights()`, `ListFlights()` etc We need to standardise, by providing a standard set of building blocks - method-resource + 1. `CreateFlightReservation()` 2. `GetFlightReservation()` 3. `ListFlightReservation()` @@ -51,6 +53,7 @@ We need to standardise, by providing a standard set of building blocks - method- ## What makes an API "good"? What is the purpose of building an API in the first place? + 1. We have some functionality that some users want. 2. Those users want to use this functionality programmatically @@ -59,13 +62,13 @@ What is the purpose of building an API in the first place? - The system as a whole must be operational. - It must do the thing users actually want. - **Non-operational** requirements: It must perform how the user expects. - - e.g. like latency + - e.g. latency ### Expressive - The system needs to allow users to express the thing they want to do *clearly* and *simply*. - The API should be designed such that there is a clear and simple way to do so. -- Avoid work arounds - if there is some functionality a user wants but there is not an easy way to do this, this is called a *workaround*. +- Avoid workarounds - if there is some functionality a user wants but there is not an easy way to do this, this is called a *workaround*. - e.g. If you have a translation API, users can create a detect language feature by constantly pinging translate endpoint. ### Simple diff --git a/mkdocs.yml b/mkdocs.yml index fc5c0b8..c82ebe3 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -25,6 +25,8 @@ theme: - search.suggest - search.highlight - search.share + - content.action.edit + - content.action.view markdown_extensions: - admonition