API stands for "Application Programming Interface".

An API is a machine-readable interface for an application. It specifies the methods by which an external program can interact with the application.

When you design an API, you are designing a user interface. Other people, who are writing their own applications, will read your API and its documentation, and attempt to write code that uses your API to get something done. You should try to make the API readable, logical, and consistent.

Other people's applications will rely on your API. They will expect it to work as originally described. Your API should (ideally) never change. If you design and implement a new version, it should run alongside the original. If you really want to move all your clients over to the new version, this should be done carefully and slowly, with lots of guidance and patience.

Generally, a graphical user interface (a GUI) should rely on an API. Computers think in one-dimensional (1-D) strings. An API takes 1-D strings as input and produces 1-D strings as output. It is relatively feasible to write tests for 1-D input and output. It is much harder to write tests for a two-dimensional (2-D) graphical interface. So: The data should be primarily processed via an API (which stores it in a database), where testing is easier. The GUI can request data from the API, display it along with various graphical controls (e.g. buttons), and send user commands (e.g. button clicks) back to the API.

Multiple GUIs can use the same API. A GUI can rely on several APIs.

A well-designed application on a local computer can be described as the combination of:
- a main program
- a database
- an API
- a GUI or command-line interface (CLI)

The main program is the bridge between the operating system and the other components. It might be set to start on boot, or when the user double-clicks a graphical icon on the Desktop, or when the user runs a command in a terminal. If a GUI is present, the main program will set it up and make everything ready to accept user input. In the case of a CLI, it will process arguments. It will primarily function as a control loop and will run until its task is complete or until the user stops the program.

Many APIs can be accessed over the web. In this case, the API and the database exist on one computer, and the CLI or GUI exists on a different computer. Each computer must run a main program. On the computer that contains the API and the database, the main program will accept web requests and route them to the appropriate API functions. On the computer that contains the CLI or GUI, the main program will process user actions, turn them into web requests, wait for the results of the web requests, and display the results to the user.

This web-based approach allows many users to use a GUI or CLI on various local computers to interact with data and functionality on a remote computer. The application is split between two computers.





What is the simplest possible API?


How about "hello, world"?


If I send "hello" to the API, I should receive the result "world". If I send anything else, I should receive "error".


So, this would be:





Here, is a URI (Uniform Resource Identifier). I think that an API should be a list of readable URIs. An API should be a legible document in and of itself.

URI behaviour should not vary depending on HTTP method (GET, POST, etc). Instead, each URI should have one and only one HTTP method associated with it. Ideally, it should be straightforward to deduce the HTTP method from the URI.

Examples: will probably use the HTTP GET method. will probably use the HTTP POST method. will probably use the HTTP DELETE method.

More broadly, each URI should have exactly one expected behaviour, which should be reasonably deducible from the URI itself. The API should be independent from the transport technology (e.g. HTTP) used between the local and remote computers.




Ok. I'll try writing the API as a document.









But: I should plan for an eventual new version of this API.









And there we are. That's the end of this project.