Working with APIs
September 25, 2024
Overview
Web API, Library API, or Framework API? This is the first question that needs to be answered, and it's how this blog post is structured.
Table of Contents
Web API
When working with a network API for the first time, three questions need to be answered:
- What type of access control does the API use?
- What type of media is the API serving?
- How is the media being served?
These three answers will greatly determine the amount of work required to build a client capable of reliably communicating with the server.
What type of access control does the API use?
The topic of access control is huge and merits at least its own post: Nordic APIs article.
What type of media is the API serving, and how is it being served?
Media generally falls under three broad categories:
- Text
- Audio/video
- Other (images, PDFs, executables, compressed archives, etc...)
In order to answer how is the media being served, we need to discuss API architectures and transfer protocols. These topics are outside the scope of this post, however, a bird's eye view is not. Let's quickly run down what to expect from modern Network APIs:
Text
Some of the most common types of APIs for serving textual data over a network are:
- REST
- GraphQL
- Websocket
REST, GraphQL, and Websockets are capable of serving any type of data, however, they're most commonly used for textual data. GraphQL is always textual. REST and GraphQL are architecture styles which use HTTP as their transport protocol, while Websocket is its own transport protocol (upgraded from HTTP).
FTP is another common transfer protocol. However, FTP gives someone direct access to a filesystem (direct access into the black box of software). API and FTP exist in different paradigms -- APIs are the connecting points of a shell which guards its black box of software.
REST
REST is the most mature of the 3 and for this reason, it's the easiest to get started. There's a lot of online resources around best practices and architectures using REST APIs.
REST is an architecture where each resource has a separate URL. Fetching, creating, updating, or deleting resources of that type utilize the different HTTP request methods to specify the action.
You'll notice that for newer services, the textual data for request and response payloads is JSON. Older services tend to use XML.
GraphQL
GraphQL was introduced in 2015, but the depth of resources online surrounding it is comprehensive. Whereas REST serves one resource per endpoint, GraphQL allows you to request a tree of related resources. For example, in REST, if you wanted information regarding a customer and their account, you would have to make two separate network requests. One request for the customer information, and another for the account information. With GraphQL, you could ask for both in a single request.
Note: a customer and a customer's account are two distinct entities because of the many-to-many relationship between them. One customer can have multiple accounts, while multiple customers may have access to one account.
GraphQL typically structures its textual data in JSON. Note: GraphQL is not to be confused with Facebook's Graph API -- they are distinct.
Websocket
Websockets enable bidirectional transfer between a browser and a server. One important part of this is that it allows servers to push data to clients without a prior request (other than the one that established the long-running websocket connection).
Audio/Video
Any data can be sent over a network as a file, and audio/video data is no exception. However, audio and video are more often sent over networks using streaming protocols. The data is sent in small chunks from a server through its API, and that data is reconstructed for playback by the client. This allows playback to occur while the data is being transferred. The length of time from when the first packet of data is sent and when playback can begin is the latency. The latency of the transfer protocol determines the possible use cases.
Steaming APIs may use one of the following common streaming protocols:
- MPEG-Dash (high latency -- okay for video streaming)
- Apple HLS (okay for video streaming)
- RTMP (okay for live-streaming)
- RTSP/RTP (good for live-streaming)
- WebRTC (very low latency -- good for real-time chat)
Building a client that interfaces with a streaming API is typically labor-intensive compared to textual APIs. Streaming protocols are typically created with a limited scope to allow for flexibility. Due to their limited scope, a lot of plumbing is required to facilitate the actual stream. For example, WebRTC is strictly a video/audio transport protocol, so information to facilitate the stream must be sent using another transport protocol, such as Websocket (this mechanism is called signaling).
Library API
Libraries typically consist of code written in the same language that's importing (including) the library. Each language typically has a package manager to help manage the third-party libraries of an application. Package managers also help manage the dependencies of third-party libraries. They often depend on other third-party libraries, creating a web of dependencies.
In the example, we used a very simple library with one public function. Libraries can be much more complex, encompassing many related features supported by multiple public functions acting as the library's API.
Two tools are critical for exploring open-source libraries:
- github.com (most popular host of open-source libraries)
- package manager for your platform (i.e. programming language)
Here's a list of the most common package manager for a few languages:
Package managers help manage third-party libraries of an application. Applications also have access to the native libraries that are included with the programming language. When using the API (public functions) of a native library, you seldom need to import anything, because the interpreter or compiler for your language already has references to the native libraries.
Framework API
Framework APIs typically take one of two forms:
- Library APIs
- Directory Structure, File Naming, and/or Function Naming (Hook / Callback)
Learn more about APIs: What is an API?
Conclusion
This was brief introduction to some important points for someone who is new to working with APIs.
Related Posts
To be updated with diagrams.