76 lines
3.4 KiB
Markdown
76 lines
3.4 KiB
Markdown
# Introduction to APIs
|
|
|
|
**API**: **A**pplication **P**rogramming **I**nterface
|
|
|
|
## What are web APIs?
|
|
|
|
- An API defines the way in which computer systems interact.
|
|
- We can find APIs in the standard libraries
|
|
- But a special type of API that is built to be exposed over a network and used remotely, "web APIs".
|
|
- Those building the API have so much control where as the users have relatively little.
|
|
- Web APIs allow you to expose *functionality* without exposing the *implementation*.
|
|
- Sometimes they allow users to take advantage of massive compute.
|
|
|
|
## What are resource-oriented APIs?
|
|
|
|
- Many web APIs act like servants.
|
|
- You ask them to do something, and they go off and do it.
|
|
- This is called *remote procedure call* (**RPC**)
|
|
|
|
### So why aren't all APIs RPC-orinented?
|
|
|
|
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.
|
|
> 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()`
|
|
4. `CancelReservation()`
|
|
5. `RescheduleFlight()`
|
|
6. `UpgradeTrip()`
|
|
|
|
- Each one of these RPCs is pretty descriptive, but we have to memorize these methods, each of which is subtly different.
|
|
- e.g. sometimes we talk about flight, other times we talk about a trip or a reservation.
|
|
- We also need to memorise which action is used in the method.
|
|
- 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()`
|
|
4. `DeleteFlightReservation()`
|
|
5. `UpdateFlightReservation()`
|
|
|
|
- Resource-oriented APIs will be much easier for users to learn, understand and remember.
|
|
- Standardisation makes it easy to combine what you already know (set of standard actions) which the resource which is easy to learn.
|
|
|
|
## 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
|
|
|
|
### Operational
|
|
|
|
- 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
|
|
|
|
### 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*.
|
|
- e.g. If you have a translation API, users can create a detect language feature by constantly pinging translate endpoint.
|
|
|
|
### Simple
|
|
|
|
- We could think of simplicity as the number of endpoints.
|
|
- However an API that relies on a single `ExecuteAction()` method just shifts complexity from one place to another.
|
|
- APIs should aim to expose the functionality users want in the most straightforward way possible, making the API as simple as possible, but no simpler.
|