piazza-fetch v1.0.0

piazza-api

A client for Piazza Q&A's API

Table of Contents

• Installation
• Quick Start
• Overview
• Users
• Schools
• Classes
• Contents
• Feed Items

Installation

This is an npm module so you can install it in the normal way.

$ npm install piazza-api

Quick Start

Login with a valid username and password:

var P = require('piazza-api');
P.login('<username>', '<password>').then(function(user) {
    console.log('Hi', user.name);
});

The client returns with User object associated with the username and can be used to call the methods listed below. After logging in, the client stores a session token from the remote server so future API calls are automatically authenticated.

Overview

Most of the calls to the Piazza API are done asynchronously via Javascript Promises. Use the then and catch methods to handled returned data.

someAsyncCall().then(function(data) {
    console.log('I got the data!');
}).catch(function(error) {
    console.log('Uh oh, there was an error:', error);
});

This client will likely include synchronous methods for interacting with the API at some point in the future.

Users

User fields include

• id String - a unique id for each user
• name String - the name of the user
• email String - the email address of the user
• roles Object - maps IDs of the user's classes to the role (for example: 'student', 'instructor')
• classIds Array - an array containing the string IDs of the user's enrolled classes
• classes Array - an array of Class objects the user is enrolled in
• lastSeenClass Class - the most recent Class the user has looked at

Users can find Classes they are enrolled in by class ID or by their role in the Class. They can also check whether or not they are enrolled in a class.

> user.getClassById('gptvhze2ToY').name
Introduction to Computers
> user.getClassesByRole('student')[0].name // this method returns an array
Introduction to Computers
> user.isTakingClass('gptvhze2ToY')
true

Schools

School fields include

• id String - a unique id for each school
• name String - the name of the school

Each class belongs to one School which can be found school field. Schools currently have no methods and only have access to their name and ID.

> school.name
Stanford University

Classes

Class fields include

• id String - a unique id for each class
• name String - the name of the class
• courseNumber String - the course number associated with the class (for example: 6.01 or CS101)
• courseDescription String - a short description of the class
• department String - the department the class belongs to
• school School - the school the class belongs to
• status String - status of the course (for example: 'inactive' or 'active')
• term String - what term the class the active (for example: 'Fall 2014')
• startDate String - date the class starts
• endDate String - date the class ends
• totalPosts Integer - total number of posts visible to instructors
• totalPublicPosts Integer - total number of posts visible to students only
• folders Array - an array of folder names as Strings
• instructors Array - an array of Objects containing the names and emails of class instructors

Classes have access to useful stats such as the response time through the getStats() method and the number of users online through the getOnlineUsersCount() method.

To access posts in the Class, use getContentByid and either pass in the Content ID or an integer. The integer must be between 1 and the number of total posts in the class, inclusive. For example calling getContentById(97) would be equivalent to using @97 in a post on the website. This method returns a Content object.

Filtering posts can be done via filterByFolder which accepts a String parameter or filterByProperty which accepts a property name such as 'unread', 'unresolved', 'hidden' (for Archived posts), 'updated', 'following', or 'instructors' (for instructor posts).

Searching can be done through the search method which takes a query in the form of a String. All three methods return an Array of Content objects that satisfy the query.

Contents

Content fields include

• id String - a unique id for each Content object
• parent Content - the Content object that this one is a child of (or undefined if none)
• classId String - the id of Class the Content object belongs to
• type String - type of Content (for example: 'question', 'note', 's_answer', 'i_answer', 'followup', 'feedback')
• title String - title of Content
• content String - text body of Content (includes HTML tags)
• created String - timestamp of when the content was created
• views Integer - number of users who have viewed the content
• folders Array - array of folder names the content is in
• tags Array - array of tags the content is associated with (includes folders)
• history Array - array of Objects containing the past states of the post, in reverse chronological order
• changeLog Array - array of Objects containing the actiosn taken on the post, in chronological order
• children Array - array of children Content objects (student answers, instructor answers, and followups)

Content objects have access to all other Content objects related to time like their parent and children. The getParent method returns the parent Content object (or none if its type is 'question' or 'note'). Both getStudentResponse and getInstructorResponse return the corresponding child Content object while getFollowups returns an array of all children Content objects that are followups of the current post.

Content objects can also get the names of their authors and editors through getAuthor and getEditors respectively.

> content.getAuthor()
John Smith
> content.getEditors()
['John Smith', 'Jane Doe']

Feed Items

Feed item fields include

• id String - an id for the corresponding Content object
• classId String - id of the Class it belongs to
• type String - type of corresponding content
• title String - title of the corresponding content
• contentSnippet String - truncated text body of the content
• views Integer - number of users who have viewed the content
• tags Array - array of tags the content is associated with
• folders Array - array of folder names the content is in
• lastModified String - timestamp of last edit
• log Array - the same as Content changelog

Feed items can be converted to Content objects when necessary using the toContent method.

> item.toContent()