Application Program Interface (API), Libraries and Documentation

Welcome to the Programmer’s Toolbox!

Imagine you are building a massive LEGO castle. You don’t have to manufacture the plastic bricks yourself; you just need to know which bricks are available and how to snap them together. In Java, Libraries are your boxes of LEGO bricks, and the API is the instruction manual that tells you how they fit together. In this chapter, we will learn how to navigate these tools so you can write powerful programs without "reinventing the wheel."

1. Libraries: Your Coding Collections

In Computer Science, a Library is a collection of pre-written classes and methods that you can use in your own programs. Instead of writing code to calculate a square root or capitalize a word from scratch, you can use code that professional programmers have already tested and perfected.

Analogy: Think of a library like a physical library of books. If you want to learn about space, you don’t write a book about space; you go to the library and "check out" a book that someone else already wrote.

2. The API: The "User Manual"

API stands for Application Program Interface. For AP Computer Science A, you can think of the API as a set of rules and descriptions for how to use a library. It acts as a bridge between you (the programmer) and the pre-written code.

The API tells you:
• What classes are available.
• What methods you can call.
• What information those methods need (parameters).
• What information those methods will give back (return types).

Did you know? You don't need to know how a method works inside to use it! As long as you follow the API’s instructions, the method will do its job. This is a core concept of abstraction.

3. Reading Documentation

Documentation is the written text that explains the API. To use a library effectively, you must be able to read Method Signatures within the documentation. A method signature is like a "contract" for the method.

A method signature includes:
1. The Method Name: What the action is called.
2. The Parameter List: What inputs the method needs (the type and the order).
3. The Return Type: What kind of data the method sends back to you (like \( int \), \( double \), or \( boolean \)).

Note: For more details on how to use these, see the upcoming chapter on "Method Signatures."

Key Takeaway:

Documentation allows you to understand how to interact with a class without needing to see the actual source code. It is your primary guide during the AP Exam.

4. Documentation with Comments

While APIs help you use other people's code, Comments help people (and you!) understand your own code. In Java, comments are ignored by the compiler—they are strictly for humans.

Types of Comments

• Single-line comments: Use two forward slashes \( // \). Everything after the slashes on that line is ignored.
Example:

\( // \) This variable stores the user's score

• Block comments: Use \( /* \) to start and \( */ \) to end. These are great for longer explanations that span multiple lines.

Initial Conditions: Preconditions and Postconditions

Professional documentation often uses comments to state Preconditions and Postconditions. These are essential for describing how a piece of code is intended to work.

• Precondition: A condition that must be true before a code segment is executed. If the precondition isn't met, the code might not work correctly.
Example: A method that calculates a square root might have a precondition that the input \( x \) must be \( \ge 0 \).

• Postcondition: A condition that the code guarantees will be true after it finishes executing (assuming the preconditions were met).
Example: After the square root method runs, the postcondition might be that the result squared equals the original input.

Memory Trick:
Pre = Before (What do I need?)
Post = After (What did I do?)

Common Mistakes to Avoid

• Ignoring Preconditions: On the AP exam, if a question says "Assume \( n > 0 \)," that is a precondition. You don't need to write code to check if \( n \) is positive; the "contract" says it already is!
• Confusing the API with the Library: Remember, the Library is the code itself, and the API is the interface/documentation telling you how to use it.

Quick Review

• Libraries are collections of classes.
• The API is the "instruction manual" for those classes.
• Method Signatures (name, parameters, return type) are the key to using the API.
• Comments (\( // \) and \( /* ... */ \)) explain code to humans.
• Preconditions are requirements before the code runs; Postconditions are the results after it finishes.