edgecase
Author: StJohn Piano
Published: 2019-04-02
Datafeed Article 95
This article has been digitally signed by Edgecase Datafeed.
This article has been digitally signed by its author.
752 words - 170 lines - 5 pages





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:

/hello
result: "world"

/[anything_else]
result: "error"




Here,
/hello
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:
/articles/1
will probably use the HTTP GET method.
/accounts/request_new
will probably use the HTTP POST method.
/cookies/10/delete
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.


API: Helloworld
Author: StJohn Piano
Date: 2019-04-02


/hello
result: "world"

/[anything_else]
result: "error"







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




API: Helloworld
Version: 1
Author: StJohn Piano
Date: 2019-04-02


/api/v1/hello
result: "world"

/api/v1/[anything_else]
result: "error"





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