Unit 1.7: APIs and Libraries

Scope: CS Awesome 2, Section 1.7

Learning Goals

By the end of this lesson, you should be able to:

1. Distinguish a library, API, package, and class.
2. Use documentation to identify available behavior.
3. Distinguish attributes from methods.
4. Recognize classes as reference types.
5. Read basic Java API notation.

Reusing Existing Code

A library is a collection of classes or other code written for reuse. An application programming interface (API) describes how a programmer can use that library.

This separation is a form of abstraction: you can use a class correctly without knowing every implementation detail inside it.

Term	Meaning
Library	Reusable implementation written by other programmers.
API	Rules and documentation for using a library.
Package	A named group of related classes and interfaces.
Class	A definition of a reference type and its available data and behavior.

Packages and Imports

Java organizes classes into packages. Some packages must be imported before their short class names can be used.

import java.util.Scanner;

The java.lang package is available automatically. It includes fundamental classes such as String, System, Integer, and Math.

String message = "ready";       // no import required
System.out.println(message);     // System is in java.lang

Reading API Documentation

API documentation commonly tells you:

• the package and class name;
• what the class represents;
• constructors for creating objects;
• fields or attributes;
• method names, parameter types, return types, and descriptions;
• preconditions, special cases, and possible errors.

Consider this small documentation excerpt for a hypothetical Beacon class:

API entry	Description
Beacon(String id)	Creates a beacon with an identifier.
void flash(int times)	Flashes the beacon the requested number of times.
String getId()	Returns the identifier.
boolean isActive()	Returns whether the beacon is active.

From the method entries, you can determine the number and type of arguments and whether a value is returned.

Attributes and Behaviors

An attribute is data associated with a class or object and is stored in a variable. A behavior is an action defined by a method.

Example idea	Category
a turtle's color	attribute
a turtle's position	attribute
moving forward	behavior/method
turning right	behavior/method

In API notation, methods always have parentheses, even when there are no parameters.

forward()      // method
turnRight()    // method
color          // attribute name, not a method call

Classes as Reference Types

A class defines a specific reference type. Once a class exists, programmers can declare variables of that type and create objects with the behaviors described by its API.

Scanner input;
String title;

Scanner and String are class names and therefore reference types.

The Dot Operator

The dot operator selects a member associated with a class or object.

System.out.println("Ready");

This expression follows several API relationships:

1. System is a class.
2. out is a class field whose type is PrintStream.
3. println is a method provided by PrintStream.

The API lets you use println without knowing how its output code is implemented.

Documentation Is Part of Programming

Do not guess a method's spelling, argument order, or return type. Check the documentation. A productive API-reading routine is:

1. identify the class;
2. find the relevant method name;
3. read the parameter list in order;
4. read the return type;
5. check preconditions and special cases;
6. construct the call using compatible values.

Practice Missions

Mission 1: Vocabulary Mapping

For each item, identify whether it is best described as a library, API, package, class, attribute, or method. Justify ambiguous cases.

1. java.util
2. Scanner
3. documentation explaining nextInt()
4. a reusable collection of graphics classes
5. a robot's battery level
6. moveForward()

Mission 2: Read a New API

Use the hypothetical Beacon table above to write:

1. a constructor call with ID A-17;
2. a call that flashes three times;
3. an expression that obtains the ID;
4. a declaration capable of storing the result of isActive().

Mission 3: API Error Review

Given void flash(int times), explain the problem with each call:

flash();
flash(2.5);
int result = flash(3);

Mission 4: Documentation Card

Design an API card for a hypothetical Thermostat class. Include two attributes conceptually, one constructor, one void method, and one method that returns a value. Specify parameter and return types but do not implement the methods.

Key Summary

Concept	Core idea
Library	Reusable code collection.
API	Specification for using library code.
Package	Namespace grouping related classes.
Class	Defines a reference type.
Attribute	Data associated with a class or object.
Method	Named behavior, shown with parentheses.
Documentation	Contract describing valid use.

Source scope: CS Awesome 2, Unit 1.7