Using APIs

API stands for Application Programming Interface, and it is a document that describes everything you need to know about using a given class. Shown below are sections of the DrawingTool API.

Click here to open the DrawingTool API

The top of an API tells you the import location (highlighted in yellow below).

The next section gives an overview of using the class. Always read this section first.

The Field Summary is a list of attributes (variables) the object keeps track of.

Attributes describe an object and keep track of its state. Typically, you don't have direct access to these variables. Instead, you modify them via methods that set and get their values.

The Constructor Summary is a list of the ways you can create and initialize objects of this class type.

The Method Summary is a list of the commands you can tell an object of this class type to do.

The rest of the API is the Constructor Detail and Method Detail. These sections are important because they give you critical information about the constructors and methods that is not covered in the summary. Shown below is the first constructor of the Constructor Detail.

Format of API methods

The general format is

modifiers - You'll learn more later but for now here's what matters:

• Access modifiers affect who can access the method.
  • If a method is declared private, you cannot access or use it, and it won't usually appear in the API. Private methods are meant for behind-the-scenes code you don't need to care about when using the class.
  • If a method is declared as protected, it means that you can't use it unless you are writing a subclass of this API class.
  • If a method is declared as public, then the modifiers section will be blank which is what you see in the Method Summary above except for the protected drawLine method.

Non-access modifiers include static and abstract which you'll learn about later in this course. If you already have some Java experience and want to read about these click here.

return type - After the modifiers (which are often blank), you will always see a return type. The return type of a method tells you the kind of information the method sends back to you when the method finishes running its code.

• A return type of void means the method does not send information back to the caller.
• Otherwise, you will see a return type such as int, double, or perhaps an object type. You'll learn how to use return types in the next lesson.

Examples

Here are some examples from the DrawingTool API. In the examples below, assume we have already declared and initialized a DrawingTool object named bob.
- To use the forward method, we must pass in a double value that represents the distance to move in pixels. A double is a number that can be a decimal or integer.

bob.forward(50);  // Moves bob forward by 50 pixels  

• To use the drawRect method, we must pass in two double values that represent the width and height of the rectangle. Also, if you read the method detail for drawRect, you'll find out that the rectangle will be centered around the DrawingTool's current location.

bob.drawRect(80, 200);  // Draws a rectangle 80 pixels wide by 200 pixels tall   
 

• Some methods require objects in their parameters. For example, to use the setColor method we must first create a Color object and then pass it into the setColor method.

Color myColor;                   // Declare a Color object myColor = new Color(255, 0, 0);  // Create and initialize myColor to Red (discussed next page)     
bob.setColor(myColor);           // Change bob's drawing color, which affects future drawing