This question already has an answer here:

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?

marked as duplicate by gnat, Community Oct 24 '18 at 23:33

This question has been asked before and already has an answer. If those answers do not fully address your question, please ask a new question.

  • 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

“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.

  • 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

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