0

I am trying to understand the difference between an Application Programming Interface and a Library and I stumbled upon this question:

https://stackoverflow.com/questions/3678665/is-there-still-a-difference-between-a-library-and-an-api

And according to one of the answers:

A library contains re-usable chunks of code (a software program).

These re-usable codes of library is linked to your program through APIs (Application Programming Interfaces). That is, this API is an interface to library through which re-usable codes are linked to your application program. In simple term it can be said that an API is an interface between two software programs which facilitates the interaction between them.

For example, in procedural languages like C, the library math.c contains the implementations of mathematical function, such as sqrt, exp, log etc. It contains the definition of all these functions.

These function can be referenced by using the API math.h which describes and prescribes the expected behavior.

That being said, an API is a specification (math.h explains about all the functions it provides, their arguments and data they return etc.) and a library is an implementation (math.c contains all the definitions of these functions).

Stating that the C header file math.h is an API, while math.c is a library.

So therefore, when we say "API", we mean "header file"? Is API exactly the same as header file?

8
  • 3
    In general, no, because "header file" is a C-specific concept and APIs are a more general concept than C. Commented Sep 4, 2022 at 8:03
  • One key difference - the file supplied as part of your C compiler is simply part of the compiler vendor's own implementation of the math.h API. The API itself is not a file but a formal written specification defined in the ISO C standard; with the specification defining more than just a set of function signatures - it also specifies other aspects including how those functions must behave and pre/post-conditions for their use where applicable (things which the vendor would probably handle in their function implementations, not in header files). Commented Sep 4, 2022 at 8:16
  • ok, so a header file is one form of API, right?
    – Noob_Guy
    Commented Sep 4, 2022 at 8:50
  • @Noob_Guy no, the physical header file supplied with your compiler is not an API at all, the API isn't a literal artefact, it's just a set of agreed rules written down somewhere (i.e. a contract). When people coin phrases such as "Use an API" they usually aren't being literal, but really mean something a bit more long-winded along the lines of "Follow the rules described by this API by picking up someone else's reusable library or service that follows those same rules" -- obviously a mouthful; most people tend not to communicate literally, so it's more likely you'd hear "Use the API" Commented Sep 4, 2022 at 9:03
  • 2
    It's not different at all, it's exactly the same, I think the issue is you may be trying to interpret the term 'API' too literally -- people obviously frequently use the term 'API' to describe header files, libraries and services, not because they are wrong, and not because they are lying, simply because they are not being literal and forensic in their use of language. If you try to over-analyse/over-interpret use of any person's language you will always find inconsistencies everywhere (except perhaps for lawyers, but software developers usually aren't lawyers). Commented Sep 4, 2022 at 9:09

4 Answers 4

7

Strictly speaking, the term API in the literal sense is not a physical artefact - i.e. it's not a source code file, library, binary or service.

The literal form of an API is an agreed set of rules, essentially a 'contract' describing the external surface area or boundary between your own code and whichever service/library/binary your code is using.

Consider the real-world concept of an interface in a banal scenario such as telephone pizza ordering - your API to a pizza restaurant would be the information written on their menu, which describes everything available to order, a telephone number to call, the prices, and information on what to expect such as delivery time or accepted payment methods.

You can pick up any telephone handset and it'll work the same way; furthermore, any member of staff working at the restaurant will be familiar with the menu and will all handle your call in exactly the same way, get you the same pizza delivered in the same amount of time, charge you the same amount of money, etc.

Physically you will be interacting with the telephone handset and verbally you'll be interacting with the staff member, yet neither are part of the pizza restaurant API because those are all interchangable with other handsets and other staff members, who will all operate in the same way by following the API contract (i.e. the same phone number, the same menu information which specifies how to order).

The same underlying principle is essentially considered (in this case) with C libraries -- your vendor has created an implementation as part of their compiler called <math.h>, which is guaranteed to follow all of the rules in the ISO C standard; the C standard also specifies things which usually won't be in a header file but are part of the API, such as preconditions, postconditions, and the behaviour offered by those functions.

Physically, your code would be using that vendor's implementation, but conceptually the API you are using is formalised in the ISO standard document; your code could use any other vendor's (standard-conforming) implementation and you'll be guaranteed by the ISO standard that it will work in exactly the same way.

3
  • I disagree. I think the pizzerias API is the pizzerias telephone (and human operator). It's a physical part of the business. The menu (and the English language) is the protocol the client must use to communicate through the telephone.
    – Juan Perez
    Commented Jun 26, 2023 at 3:22
  • @JuanPerez An API is not an implementation nor physical resource but a contract/specification. The telephone and operator in this analogy are a physical transport mechanism, meaning they form part of the implementation. In software terms, the implementation might involve resources such as sockets and memory buffers. The point about an API being a contract is important because it emphasises the fact that an API is not any of these physical implementation details, but a specification which any implementation must conform to (on either side) to work correctly. Commented Jun 26, 2023 at 7:38
  • The distinction here is an important one to make, particularly with reference to the standard C headers in the OP -- millions of people use those headers and many of them rely upon a compiler vendor's implementation of them offering the same definitions and behaviours as every other vendor. This guarantee is not provided by any vendor or implementation but in the API, which is information enshrined inside the ISO C standard document which specifies a set of guarantees, definitions and behaviours that all consumers can expect from their compiler, and which vendors must conform to. Commented Jun 26, 2023 at 7:45
3

The .h/.c analogy is just an example. The API is a means to access functionality (of a library). Think of a literal library, a place that has a lot of books from which you can pick some to take home and bring back at a later time. The library would be the building with the books.

Now, there is a procedure you would need to follow in order to get to those books. First you would need a membership, show your id and all. Then you get a nice card, perhaps with a bar code or a chip on it. Then you would go to a catalog that tells you where the books are you may be interested in. Once you pulled them from the shelf you bring them to the counter and hand over your card. The person registers the books to your name and gives you back your card and you go home with the books.

All these formalities to finally get those books would be the API. In order to use the library you would first need to learn the API and once you understand that, you know how to use that library, that is your access to it.

0

Consider this counterexample:

You have a file named math.h that contains:

double sin(double x);

Then the file math.c implements this function.

Now you do a simple change to math.h:

double dblsin(double x);
#define sin dblsin

Did your API change? I'd say mostly not, although it's very ugly to use preprocessor defines to change a function name, and it could have nasty side-effects for example in functions that use sin as a local variable or parameter name, especially if there's another local variable or parameter named dblsin.

But you header file did change even if the API didn't.

The header file is something that describes the API. However, what the actual API is, is in my opinion more abstract.

It's also possible to imagine cases where the header file doesn't change, but the API does change a lot, at least if the header file contains no comments that describe how it must be used.

0

In short

The term API covers at the same time an interface implementation (for the code to use) and an interface specification (for the humans to understand).

While the API specification is abstract and independent of any programming language, the API implementation is language/middleware specific. In C in particular, there is some overlap between a header and an API, but you can have parts of a header that don't belong to the API, and conversely, you can have parts of an API that are not defined in a header.

More arguments

Is there a definition of API?

There is no authoritative definition of what an API is. But IEEE's SWEBOK provides a good start, as it is an technical report endorsed by the international standard organisation (ISO):

An application programming interface (API) is the set of signatures that are exported and available to the users of a library or a framework to write their applications. Besides signatures, an API should always include statements about the program’s effects and/or behaviors (i.e., its semantics).

The case of C and its headers

In C, any public symbols may be "exported" without necessarily having to be in a header. A non static function defined in some compilation unit will be exported to the linker even if it's not declared in some header.

Such element could be used by any other modules, provided they know how to use the symbol (e.g. hand-crafted assembler if the parameters and parameter passing convention is known, or independent C compilation unit that just declares the same function as external).

So, the API is defined independently of the header. But in practice, in C and some other languages, a header is the easiest and less error-prone manner to define once the API and make it available to other compilation units. Because it allows to use the same declaration on the "exporting" and "importing" side.

API specification vs. API implementation

Until now I only addressed the implementation of the API (with or without headers in C, but other languages use different techniques to export and import APIs.

Such an API implementation is of little use without an API specification which explains how to use the elements and what their effects are. The specification explains exactly this. For an obvious function like sin() the name of the function is almost already its specification, but there are lots of other APIs that are less obvious.

Sometimes, e.g. for WebAPI, the API is only defined by a specification: no header defines how to structure the API call over http. You have to know which server to send what request to get the results defined in the API specifications. On the other side, other distributed technologies rely on special Interface Definition Languages used by middleware to connect heterogeneous and remote system components.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.