What exactly does it mean to write an API for an OO language?

Question

I have been asked to write an API for a high-level OO language of my choosing (I'll be using Java). The API needs to perform specific functions, of course, but they are very basic things that I know I can accomplish.

I'm familiar with the concept of an API for a web application and that's straightforward enough, but what exactly does it mean to write an API for an OO language? In Java's case, does this mean writing a package that can be imported and provides the desired functionality via classes/functions, so I would write a) the package and b) a separate module to test it? (For clarification, I have been provided no information other than "write an API" and "it needs to do X, Y, and Z". Further clarification: I mentioned the web application API concept just to show that I know what an API is. This is not any sort of web API whatsoever.)

Answer 1

There are different definitions depending on the context and who you ask.

Some people call all public types that are exposed by a module an API. By this very broad definition almost every library or package has an API. I think this is a quite common definition but not everyone agrees with it.

At a more abstract level, an API is a kind of contract or specification that defines some functionality. An API is more like a well defined interface of a module or service that is used to separate the public available functionality from it's internal implementation. A good example of this kind of API are the Java EE APIs.

Practically, in Java an API usually consist mostly of Interface types. The functionality is defined by the methods of the interface and by the documentation. The API itself does not need to have any functionality on its own (it can have some basic default classes or helper classes though).

It's up to another class to implement the interface and provide implementations of the defined functionality. Those implementations shouldn't violate the contract which is defined in the documentation.

If a some application wants to use the API, it only accesses the interface and never the implementing classes. This is the principle "Program to an interface, not an implementation". In my opinion this is the most important aspect of APIs and is what separates the API from regular interfaces. It makes the API reusable and enables the internal implementation to change without breaking the API.

Of course to actually use an API, there has to be some kind of mechanism to get an instance of a class that implements the API. Usually it's some kind of factory method or dependency injection.

The packaging usually depends on the API's usage. API as defined by the first definition usually are included in the jar of their library, because it wouldn't make sense to import them alone. If there are multiple implementations of an API then the API should be be packaged separately from the implementations.

Answer 2

Yes, you just need to write the classes need to implement the desired functionality. Make sure whatever functionality is requested can be accessed by some other programmer using your code. (Methods they need to use should be public for example).