3

I am trying to understand what exactly an API is.

From my current understanding, an API (Application Programming Interface) is a contract provided by a software instance, that guarantees a defined set of behaviors, which are triggered by a defined set of actions.

An API is a "public" sort of construct, as it defines the rules of communication with the outside world.

Similarly, a Java Interface in a nutshell, is also a construct, that a given Java Class (which implements that interface) has to provide, e.g. provide the functionality defined in that Interface (by writing the function implementations).

Both seems to be doing virtually the same thing, defining a set of behaviors that will be triggered if the right action (e.g. call, or format of the call) is taken.

So is it correct to refer to Interfaces provided by Java (e.g. Collections) or even ones written by me, as APIs?

Ankit Beniwal
  • 103
  • 3
gEdringer
  • 141
  • 4
  • There are different technical roles, perspectives and usages of the term _interface_ resp. _API_. Though under a quality API I would understand an algebraic set of operations that are more or less complete and cover all you might want to do. Where the target topic is some business related one. So I would not call `Comparable` an API, a `Deque` just might do. An UML system component thingy. _Subjectively._ – Joop Eggen Oct 24 '18 at 11:56

1 Answers1

5

“API” is a very elastic term, and can describe anything from a set of URLs to a method signature.

  • Yes, Java interfaces describe an API, or at least part of an API.
  • But not every API has a Java interface.

When you use Java interfaces to describe an API, note what the interface contains: just a couple of method signatures, and possibly some JavaDoc. The signature describes the API for the type checker, but cannot describe things like preconditions of this method. These extra requirements might be expressed in the documentation for that interface, but it is not really part of the interface itself. E.g. there are some marker interfaces like Serializable that are empty and declare no methods at all, but have some meaning that cannot directly be expressed within Java's type system.

You shouldn't approach interfaces with a thought process like “this is an API → let's use interfaces”. Instead, interfaces describe what kind of methods an object offers to a consumer of that object. A path to good interfaces often leads through a short refactoring process:

  • This function uses another object. I wish I could use different kinds of objects…
  • Describe how we use that object, using an interface. So here we need to getBar() and over there our object needs to frobnicate(Something).
  • Implement the interface in all relevant classes. If you have no control over the class, use the Adapter Pattern to make it conform to the new interface.

Note that extending a base class inherits both an interface/API and the implementation for that API. It turns out that this is not ideal, and that it is usually better to use Java interfaces for interface-inheritance, and composition for implementation-reuse.

amon
  • 132,749
  • 27
  • 279
  • 375
  • 1
    When reading that, it make me feel like an API could be considered as all the entry points (URL, inteface, ...) that your app/library/framework/module provides. – Walfrat Oct 24 '18 at 12:04
  • 2
    @Walfrat Yes! the point about entrypoints is very good. But return values and arguments are also part of the API, which makes the API much larger than it might appear at the surface. – amon Oct 24 '18 at 12:10
  • "note what the interface contains: just a couple of method signatures". Isn't it more accurate to say method headers? Method signature only includes the method name as well as a parameter list (parameter names and types). – Sebastian Nielsen Oct 31 '19 at 20:42
  • @SebastianNielsen The term “signature” is commonly used in the context of programming languages. The term “header” is not, or invokes misleading connotations from C. Borrowing C terminologies, it would also be correct to talk about “declarations”. Of course, my answer isn't entirely correct since Java 8 introduced default methods. – amon Nov 02 '19 at 13:57