Introduction

ScratchAPI is a simple Java interface to the Scratch 2.0 website. It is not nearly done yet, and will later include several features, but it takes time. :P

If you want to see a list of features to be added, click here > https://github.com/Arinerron/ScratchAPI/issues/1 Also, if you're wondering why everything is indented with 8-width tabs, it's because GitHub is being irritating. They are supposed to be 4 spaces.

Documentation

Session Management

Create a user session and log in:

ScratchSession session = Scratch.createSession("username", "password");

ScratchSession session = Scratch.register("username", "password", "gender", birthMonth, "birthYear", "location", "the@email.here"); // All fields case sensitive-- to be documented better later...

Get information about the session:

String username = session.getUsername();
String csrftoken = session.getCSRFToken();
String expiration = session.getExpiration();
String sessionid = session.getSessionID();
ScratchCloudSession cloudSession = session.getCloudSession(projectid); // Cloud sessions are documented a while down
ScratchUser user = session.you();

Log session out:

session.logout();

Users

Create a user instance:

ScratchUser user = new ScratchUser("username");

Get information about user:

user.update(); // Run this first! It updates the info about the user.
String username = user.getUsername();
String status = user.getStatus();
String bio = user.getBio();
String country = user.getCountry();
Date joinDate = user.getJoinDate();
int messageCount = user.getMessageCount();
List<ScratchProject> favoriteProjects = user.getFavoriteProjects(limit, offset); // limit max 20

Follow and unfollow the user:

user.setFollowing(session, true); // Follow user
user.setFollowing(session, false); // Unfollow user

Comment on user profile:

user.comment(session, "Example comment"); // You can't comment too fast, remember the delay

Projects

Create a project instance:

ScratchProject project = new ScratchProject(projectid); // 'projectid' is an int

Get information about project:

project.update(); // Run this before everything else
String title = project.getTitle();
String description = project.getDescription();
ScratchUser creator = project.getCreator();
int viewCount = project.getViewCount();
int loveCount = project.getLoveCount();
int favoriteCount = project.getFavoriteCount();
int projectid = project.getProjectID();
ScratchProjectManager manager = project.getProjectManager(); // Useless as of now
String resourceurl = project.getResourceURL();
String shareDate = project.getShareDate();
String thumbnailurl = project.getThumbnailURL();

Love and unlove the project:

project.setLoved(session, true); // Love project
project.setLoved(session, false); // Unlove project

Favorite and unfavorite the project:

project.setFavorited(session, true); // Favorite project
project.setFavorited(session, false); // Unfavorite project

Comment on project:

project.comment(session, "Example comment"); // You also can't comment too fast, remember the delay

Cloud Data Management

Create a cloud session:

ScratchCloudSession cloudSession = session.getCloudSession(projectid);

Add and remove a cloud event listener:

ScratchCloudListener listener = new ScratchCloudListener() {
    public void onSet(int projectID, String name, String value) {
        // insert code here...  
    }

    // Later TODO add onEnd
}

cloudSession.addCloudListener(listener); // add
cloudSession.removeCloudListener(listener); // remove

Get the cloud symbol (☁):

char cloudSymbol = Scratch.CLOUD;

Get information about cloud session:

int projectid = cloudSession.getProjectID();
ScratchSession session = cloudSession.getScratchSession();
String cloudToken = cloudSession.getCloudToken();

Get a list of cloud variables:

List<String> variables = cloudSession.getVariables();

Get a cloud variable's contents:

String contents = cloudSession.get(Scratch.CLOUD + " variable"); // The space is needed!

Set a cloud variable's contents:

cloudSession.set(Scratch.CLOUD + " variable", "new value"); // Strings should work...

Rename a cloud variable (untested):

cloudSession.rename(Scratch.CLOUD + " variable", Scratch.CLOUD + " new name");

Create a cloud variable (untested):

cloudSession.create(Scratch.CLOUD + " newVariable", "value");

Delete a cloud variable (untested):

cloudSession.delete(Scratch.CLOUD + " variable");

Close the cloud session:

cloudSession.close();

Statistics

Get total project count:

 // Updates every 24hrs (thanks @thisandagain)

int totalProjectCount = ScratchStatistics.getProjectCount();
int totalStudioCount = ScratchStatistics.getStudioCount();
int totalUserCount = ScratchStatistics.getUserCount();
int totalCommentCount = ScratchStatistics.getCommentCount();
Date timestamp = ScratchStatistics.getTimestamp();

Miscellaneous

Set the default User-Agent:

Scratch.setUserAgent("insert User-Agent here");

Get a list of Scratch users:

List<ScratchUser> users = Scratch.getUsers(limit, offset); // Max limit is 20

Exceptions

List of exceptions:

edu.mit.scratch.exceptions.ScratchException
edu.mit.scratch.exceptions.ScratchLoginException
edu.mit.scratch.exceptions.ScratchUserException
edu.mit.scratch.exceptions.ScratchProjectException
edu.mit.scratch.exceptions.ScratchStatisticalException

Examples

Follow yourself and kaj

new ScratchUser(session.getUsername()).setFollowing(session, true); // Yourself
new ScratchUser("kaj").setFollowing(session, true); // Kaj

Open alert dialog when you get a message

final String user = "griffpatch"; // Change this to your username!

Timer timer = new Timer();
timer.schedule(new TimerTask() {
    public ScratchUser target = new ScratchUser(user);
    public int previous = -1;

    @Override
    public void run() {
        try {
            int count = target.getMessageCount();
            if(previous == -1) {
                previous = count; // This means the program just started.
            } else 
                if(count > previous) {
                    previous = count;
                    javax.swing.JOptionPane.showMessageDialog(null, "The account " + user + " on Scratch now has " + count + " messages.");
                }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}, 0, 5 * 1000); // Updates every 5 seconds

Warning: if you are famous, the number of dialogs from your messages will seriously get annoying.

Arinerron / ScratchAPI

readme