1.7 Application Program Interface (API) and Libraries

TLDR

Libraries are collections of classes, and an API specification is the documentation that tells you how to use those classes without seeing their internal code. In AP Computer Science A, your job is to read that documentation to identify a class's attributes (its data, stored in variables) and its behaviors (what it can do, defined by methods).

An API specification is the documentation that tells you how to use the classes in a library without showing their code. Getting comfortable with attributes, behaviors, packages, and documentation now makes the Math class, the String class, and any provided classes much easier to work with later.

How APIs Describe the Classes in a Library

• A library is a collection of classes, and an API specification explains how to use those classes.
• API documentation is essential for understanding a class's attributes and behaviors, since you use a class without seeing its internal code.
• Attributes are the data related to a class and are stored in variables; behaviors are what instances can do and are defined by methods.
• A class defines a specific reference type, and existing classes can be used to create objects.
• Classes in APIs and libraries are grouped into packages.

Key Concepts

APIs Tell You How to Use a Class

An application programming interface (API) specification is the documentation that informs the programmer how to use the classes in a library. The "interface" part means it shows you what you can do with a class without revealing how it works internally.

Think of an API like a restaurant menu. The menu lists the dishes and describes them, but it does not hand you the recipes. API documentation works the same way: it tells you what methods a class has and what they do, but not the internal code behind them. This is why you can use a class confidently just by reading its documentation.

Libraries Are Collections of Classes

A library is a collection of classes that you can reuse instead of writing everything from scratch. Existing classes and class libraries can be utilized to create objects, which saves you from rebuilding common functionality yourself.

Each class in a library defines a specific reference type. When you create an object from one of these classes, the variable that holds it stores a reference to that object rather than the object itself.

Packages Group Classes Together

Classes in APIs and libraries are grouped into packages. A package is a way of organizing related classes under a shared name. Package names use dots to show hierarchy, similar to nested folders.

One package worth knowing now is java.lang, which contains fundamental classes like String, Math, and Object. Classes in java.lang are available by default, which is why you can use String and Math without any extra setup.

Attributes and Behaviors

Every class describes two things: attributes and behaviors.

• Attributes are the data related to the class. They are stored in variables.
• Behaviors are what instances of the class can do, or what can be done with them. They are defined by methods.

When you read API documentation, you are really looking for these two things. The variables tell you what data an object holds, and the methods tell you what that object can do.

Code Examples

The classes below come from java.lang, so they are available by default. These examples show how reading a class's documented behaviors lets you use it correctly.

</>Java
// Using the Math class from java.lang (available by default)
public class MathAPIDemo {
    public static void main(String[] args) {
        // Math methods are class methods, so call them on the class name
        double squareRoot = Math.sqrt(16);   // returns 4.0
        double power = Math.pow(2, 10);       // returns 1024.0
        double absoluteValue = Math.abs(-42); // returns 42 (an int, widened to 42.0 when stored in the double)

        // random() returns a double >= 0.0 and < 1.0
        double random = Math.random();

        System.out.println(squareRoot);
        System.out.println(power);
        System.out.println(absoluteValue);
        System.out.println(random);
    }
}

Reading documented behaviors before calling a method:

</>Java
// Using documented String behaviors (String is in java.lang)
public class StringAPIExample {
    public static void main(String[] args) {
        String text = "Hello World";

        // int length() returns the number of characters
        int len = text.length();             // returns 11

        // String substring(int from, int to) returns chars from..to-1
        String sub = text.substring(0, 5);   // returns "Hello"

        // int indexOf(String str) returns the first index, or -1 if not found
        int index = text.indexOf("World");   // returns 6

        // boolean equals(Object other) compares character sequences
        boolean same = text.equals("Hello World"); // returns true

        System.out.println(len);
        System.out.println(sub);
        System.out.println(index);
        System.out.println(same);
    }
}

Notice that you never see the code inside length(), substring(), or Math.sqrt(). You only need the documented behavior to use them correctly.

Reading Provided Class Documentation and Tracing Calls

Reading a Provided Class: When a question gives you a class, scan its documentation for two things: the attributes (variables that hold data) and the behaviors (methods you can call). You do not need to know how a method is written to use it. You only need to know what it does, what it takes in, and what it returns.

Code Tracing: When you trace code that calls library methods, treat the documented behavior as the source of truth. For a method like substring(int from, int to), the documentation tells you it returns the characters from index from up to but not including to. Trust the description rather than guessing.

Common Trap: Match every method call to what the documentation actually says. Check the parameter types, the order of parameters, and the return type before you assume an output. Many wrong answers come from skipping past these details.

Common Misconceptions

• Misconception: You need to see a class's internal code to use it.
  Actually: You do not. The API specification gives you the documented attributes and behaviors, which is all you need to use the class.
• Misconception: An API and a library are the same thing.
  Actually: A library is the collection of classes. The API specification is the documentation that explains how to use those classes.
• Misconception: Every class must be imported.
  Actually: Classes in java.lang, such as String, Math, and Object, are available by default and do not need extra setup.
• Misconception: Attributes and behaviors are the same kind of thing.
  Actually: Attributes are data stored in variables, while behaviors are actions defined by methods. Keep the two ideas separate when you read documentation.
• Misconception: Methods on a String change the original String.
  Actually: They do not. String methods return new values, and the original String object stays the same.

Related AP Computer Science A Guides

• 1.4 Assignment Statements and Input
• 1.13 Creating and Storing Objects
• 1.8 Documentation With Comments
• 1.9 Calling a Void Method With Parameters
• 1.6 Compound Assignment Operators
• 1.14 Calling a Void Method