Difference between API and protocol?

Question

What's the difference between an API and a protocol?

To use a specific example: Is Coinbase's choice to refer to its WebSocket client specification as an "API" appropriate? It seems that many companies in their space followed their naming trend. For example, FTX calls this client specification their WebSocket API. This seems like a misuse of the term "API".

Not all API are websocket API. For a c++ library, headers form an API for example — JayZ, Aug 02 '22 at 14:58
A specification of something can in principle specify an API as well (by which I mean the interfaces, as in, different libraries would have to implement the same API to be compliant). But a specification can also be more high-level, e.g. it could prescribe things like exchange data formats of messages and certain high-level rules (an overlying standard or protocol of some sort), where implementations are free to define their own APIs for client code (making clients protocol-independent, in principle). — Filip Milovanović, Aug 02 '22 at 15:52
You can write [a specification for a salt shaker](https://patents.google.com/patent/US888066). Just so long as you're, you know, specific. — candied_orange, Aug 02 '22 at 15:59
The simplest way I can think to disambiguate them; API describes the external *surface area* of a "thing" I want to communicate with. A protocol describes *how to communicate*, but not *what* I will be communicating with. For example, The English Language is my protocol for phoning up to order a Pizza, but the API of the Pizza place is their menu and the employee picking up the phone. — Ben Cottrell, Aug 02 '22 at 17:05
@BenCottrell I was all focused on work until you said "Pizza" — toddmo, Oct 15 '22 at 20:54

score 5 · Answer 1 · answered Aug 02 '22 at 15:30

5

The c2 wiki distinguishes them like this:

An API provides a library that you must link with to use the services. This tightly binds the client and server together. The API tends invade all code layers and creates massive dependencies between layers. It also tends to be simple to use.

A protocol defines a standard request response layer and a common transport. Nothing other than the standard binds the client and server together. Protocols are more complex to use as they are less direct and take a lot of serializing/deserializing/dispatching type logic.

When I skim the ITCH protocol you linked I don't see it teaching me method names or dictating a language to use. I see it telling me what bits to set and where. That's a protocol.

answered Aug 02 '22 at 15:30

candied_orange

102,279
24
197
315

2

I saw the c2 wiki. Their definition of an API seems to be incorrect/outdated and matches what most call a "client library". And for example, their definition fails in that a typical REST API does not require you to link a library. Even if we assumed this definition is mainstream, neither Coinbase nor FTX examples require linking of a library. Borrowing from more reliable resources, Google, Twilio, Stripe all make good examples of distinguishing their APIs from their client libraries, whereas this c2 wiki conflates the two. – Katie Aug 02 '22 at 15:58
@Katie yes it does. It's just a really popular one. – candied_orange Aug 02 '22 at 16:01
Which popular library are you referring to? – Katie Aug 02 '22 at 16:03
@katie Apache ;-) – candied_orange Aug 02 '22 at 16:06
4

@Katie - the problem is that there isn't an authority that can impose a universal definition. These terms might have a relatively consistent informal meaning, but if you want to get precise, you have to consider each term in context in which it appears, and sometimes documents will explicitly state the definition, and *that* establishes the precise meaning of the term within that document or project. This is not unusual - this happens even in rigorous fields such as mathematics, and certainly in science and engineering. 1/2 – Filip Milovanović Aug 02 '22 at 16:34
2

People who built the Internet were thinking in terms of communication protocols, whereas in programming we deal with a set of public procedures (or entities that have procedures) that we can call - the API. What the industry calls REST APIs (which is *very* different from Roy Fielding's original REST, and really, a misappropriation of the name) is essentially a particular style of doing remote procedure calls. It's not about a library or a remote service, it's about the interface; a client relies on an API directly, so an implementation that doesn't adhere to an API will break the client. 2/2 – Filip Milovanović Aug 02 '22 at 16:34
@FilipMilovanović if we want to argue for blurry lines I can argue that every protocol is an API because [protocol buffers](https://developers.google.com/protocol-buffers) exist. The terms have their own history and connotations. Yes you can look at them as being the same thing but you don't have to. Especially since most of don't. Text files are technically binary data but when I say it's binary data I'm rarely talking about a text file. c2's point is about our expectations. If it's a protocol we expect to be able to write our own code against it from scratch. – candied_orange Aug 02 '22 at 16:50
1

I wasn't arguing for blurry lines, just wanted to point out that if you want a precise, rigorous definition, you have to be aware that it will only be applicable, in its full rigorousness, within some context, and that you can't necessarily transplant it to some other context as is - since Katie was mentioning things like "incorrect/outdated" and "mainstream" in the first reply. – Filip Milovanović Aug 02 '22 at 17:20
BTW, just in case my comments came off that way - I wasn't arguing that they can be seen as the same thing at all - I was maintaining the distinction. I was just addressing Katie's point about why we say "REST API" even though we don't link a library (as opposed to when you link a library - with *some* API not prescribed by the protocol - to let it handle the details of the protocol for you). – Filip Milovanović Aug 02 '22 at 17:20
1

@FilipMilovanović You're right, rigorous definitions of these are by no means wide spread. I was aiming to get closer to traditional usage. Now this is just me talking, but I always thought of API's as riding on top of a protocol. When you're writing at the protocol level you're using tools that don't know the protocol. Conforming to it is your job. When you're writing at the API level you're talking to some tool that knows of the API and the protocol it rides on. Doesn't matter if it's a library, framework, or language. But that's just me. What do you think? Incorrect/outdated? – candied_orange Aug 02 '22 at 18:04
No, no, I pretty much agree with you. My comments were not objections to what you wrote, I have no fundamental objections to that - I upvoted your answer (I think mine was the first upvote, 2h+ ago, when I left the comment on the question itself). My comments here were addressing OP's objections, which were about details in the c2 wiki text - which is fair, I guess, but you can still rescue the essence of the answer, even if some of the details in the quote are not generalizable. 1/2 – Filip Milovanović Aug 02 '22 at 18:31
So, I was trying to steer the OP towards a way to generalize. Yes, an API riding on top of a protocol makes sense in the implied context of networking, I agree with that picture. But based on what the OP wrote, as they are looking at various references online, the definitions of "API" they might be encountering might not all be in the networking context (eg API to a math library, without any associated formal protocol). So I'm trying to get them to a place where the term API can be defined without any reference to the concept of a protocol (and then you can contrast the two from that POV). 2/2 – Filip Milovanović Aug 02 '22 at 18:31
@FilipMilovanović Not worried about the voting, but thank you. I'm simply checking my thinking because I wanted to use these comments to inspire a good edit. Maybe it's from my days of writing assembly but I don't think of networking as all that different from the rest of the communication happening in the computer. Just comes with an ISO stack and the occasional session token. If you want to see the protocols on it grab a copy of Wireshark. But even function calls have a protocol. Push args on the stack in a conventional order along with some way to count them and calls can communicate.1/2 – candied_orange Aug 02 '22 at 18:40
@FilipMilovanović But to your point, yes a good API can abstract the protocol to the extent that a completely different protocol can be used to support it. Just so long as each end of the communication uses the same protocol. The API would be untouched. Using [Ben's](https://softwareengineering.stackexchange.com/questions/440182/difference-between-api-and-protocol/440184#comment966344_440182) example you can order from the same menu using English, French, or [ASL](https://www.nidcd.nih.gov/health/american-sign-language) to talk to your server. 2/2 – candied_orange Aug 02 '22 at 18:56
"I don't think of networking as all that different from the rest of the communication happening in the computer" - I guess that's fair. "even function calls have a protocol" - true, but that gives me an idea - we might use that POV as a good lens to think about this. When designing an API to, say, a class library, calling conventions and such typically don't come up at that level. So the focus is on procedures/types and associated semantics, and protocol-like aspects of that (if any) are not explicitly separated. You start explicitly worrying about protocols as a separate issue ... 1/2 – Filip Milovanović Aug 02 '22 at 20:08
...when the underlying technological substrate (for lack of a better term) becomes heterogeneous in some way that you can't ignore - there's interop, or cross-platform concerns, or a network of heterogeneous nodes involved. If one takes that POV, protocols seem to be primarily concerned with imposing structure or order on such environments by agreement (or decree), whereas with APIs, the parties that are interacting are in some sense already on level ground (even if it's only level because of the underlying protocols). Perhaps that justifies seeing the API concept as independent, in a way. 2/2 – Filip Milovanović Aug 02 '22 at 20:08
@FilipMilovanović Calling conventions can go heterogeneous. Just try calling C libraries from Java. It can be done. But you have to tell it what you’re doing so it uses the right protocol/call convention. Thus the API becomes a leaky abstraction. – candied_orange Aug 02 '22 at 22:19
That's what I'm saying - because you have a heterogeneous environment (Java and C), you have to think about calling conventions (which you rightly likened to a protocol). – Filip Milovanović Aug 03 '22 at 00:48
Perhaps we (or I) made this whole thing a hazy by going in dozens of directions, but I guess the gist of what we're discussing is whether to think of APIs as built over protocols (in your more broader sense), or to conceptualize APIs as "here's an interface to something, here's what it means, here's how it's used" (which, sure, might have protocol-y aspects to it). And then you might have a separate spec for the protocol that governs nontrivial aspects of the interaction/communication, and potentially has a life of its own, independent of the API in question. Maybe that's too fastidious – Filip Milovanović Aug 03 '22 at 00:48
The quote is taken out of context and highly misleading as an answer to the question. Tha page does not describe what an API is, it describes linking a client side library to connect to a service. – JacquesB Jun 27 '23 at 09:39

score 1 · Answer 2 · answered Aug 02 '22 at 17:22

In computer science, a protocol pertains specifically to communication. This means you have at least two parties and the protocol defines how each is to behave.

An API is a static definition of the way some resource can be accessed and/or utilized. It is typically call-based where a protocol is message-based.

score 1 · Answer 3 · answered Jun 26 '23 at 03:13

A protocol is a specification, a set of rules a message (and it's response) must follow.

An API is the part of an application that is exposed to the user (whether human or robot, they are mostly indistinguishable by the program). Within the full set of functions that make up a program, the API is the subset of functions that deal specifically with receiving input and deliver output from/to the user.

In fact, even libraries have APIs, not just programs. It's the subset of functions that are "exposed".

In the context of web client-server architecture, the API is the exposed part of the server application. The client side is the user that makes the requests.

The client must send requests following whatever protocol the API demands. To do this, the server developers might create a public library for it. But it's not necessary, an independent user could write his own requesting functions, as long as they follow the protocol they'll work.

In a more general sense, for example, the part of Powershell that handles the CLI's input is part of Poweshell's API. The expected shape of the input itself is the protocol.

Difference between API and protocol?

3 Answers3