# 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*.