101 lines
4.8 KiB
Markdown
101 lines
4.8 KiB
Markdown
# Introduction to APIs
|
|
|
|
**API**: Application Programming Interface
|
|
|
|
## 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. 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 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
|
|
|
|
- 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.
|
|
- **Make the common case fast**
|
|
- Whenever you add something that might complicate the API for the benefit of an advanced user, it is best to keep this complexity hidden from a basic user.
|
|
- This keeps the more frequent scenarios simple and easy whilst enabling advanced features for those who want them.
|
|
- e.g. Image a translation API. `GET /translate?lang=en`, allowing the user to add a specific language model as a mandatory field is complex for the average user and will slow down basic scenarios.
|
|
|
|
### Predictable
|
|
|
|
APIs that rely on repeated patterns applied to both the API surface definition and the behaviour.
|
|
|
|
Users very rarely learn an entire API, they learn the parts they need to and make assumptions when they need to make additions. e.g. if a query parameter is called text in one endpoint, it should not be called string or query in another.
|
|
|
|
APIs that rely on **repeated**, **predictable** patterns are easier and faster to learn; and therefore better.
|
|
|
|
### Summary
|
|
|
|
- Interfaces are contracts that define how two systems should interact with one another.
|
|
- APIs are a special type of interface
|
|
- Web APIs are again a special type of API that is exposed over a network.
|
|
- **Resource-oriented** APIs are a way of designing APIs to reduce complexity by relying on a standard set of actions, called *methods*, across a limited set of resources.
|
|
- Good APIs are generally: *operational*, *expressive*, *simple* and *predictable*.
|