Java library for the Clever API
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.circleci
docs
gradle/wrapper
override
src
.gitignore
.swagger-codegen-ignore
.travis.yml
Makefile
README.md
build.gradle
build.sbt
clever-java.properties
git_push.sh
gradle.properties
gradlew
gradlew.bat
pom.xml
settings.gradle

README.md

Clever Java Library

Client library for the Clever API

Installation

Manually install the Clever JAR: https://github.com/Clever/clever-java/releases

Maven users

Add this dependency to your project's POM:

<dependency>
    <groupId>com.clever</groupId>
    <artifactId>client</artifactId>
    <version>1.0.1</version>
    <scope>compile</scope>
</dependency>

Gradle users

Add this dependency to your project's build file:

compile "com.clever:client:1.0.1"

Others

At first generate the JAR by executing:

mvn package

Then manually install the following JARs:

  • target/client-1.0.1.jar
  • target/lib/*.jar

Getting Started

Please follow the installation instruction and execute the following Java code:

import io.swagger.client.ApiClient;
import io.swagger.client.ApiException;
import io.swagger.client.Configuration;
import io.swagger.client.api.DataApi;
import io.swagger.client.auth.OAuth;
import io.swagger.client.model.*;

public class CleverAPI {

    public static void main(String[] args) {
        ApiClient defaultClient = Configuration.getDefaultApiClient();

        // Configure OAuth2 access token for authorization: oauth
        // Note: This is hard coded for demo purposes only. Keep your access tokens secret!
        // https://dev.clever.com/docs/security#section-security-best-practices
        OAuth oauth = (OAuth) defaultClient.getAuthentication("oauth");
        oauth.setAccessToken("TEST_TOKEN");

        DataApi api = new DataApi();

        try {
            StudentsResponse students = api.getStudents(10, null, null);
            for (StudentResponse student : students.getData()) {
                System.out.println("Student IDs: " + student.getData().getId());
            }
        } catch (ApiException e) {
            System.err.println("Exception:");
            e.printStackTrace();
        }
    }
}

Events Usage

Since events are polymorphic, we use the type to determine how to cast them. For example:

public void processEvents(EventsApi api) {
    EventsResponse eventsResponse = api.getEvents(10, null, null, null, null);

    for (EventResponse eventResp : eventsResponse.getData()) {
        if (eventResp.getData().getType() == "students.created") {
            StudentsCreated event = (StudentsCreated)eventResp.getData();
            // Process the event...
        }
    }
}

Documentation for API Endpoints

All URIs are relative to https://api.clever.com/v2.0

Class Method HTTP request Description
DataApi getContact GET /contacts/{id}
DataApi getContacts GET /contacts
DataApi getContactsForStudent GET /students/{id}/contacts
DataApi getCourse GET /courses/{id}
DataApi getCourseForSection GET /sections/{id}/course
DataApi getCourses GET /courses
DataApi getDistrict GET /districts/{id}
DataApi getDistrictAdmin GET /district_admins/{id}
DataApi getDistrictAdmins GET /district_admins
DataApi getDistrictForContact GET /contacts/{id}/district
DataApi getDistrictForCourse GET /courses/{id}/district
DataApi getDistrictForDistrictAdmin GET /district_admins/{id}/district
DataApi getDistrictForSchool GET /schools/{id}/district
DataApi getDistrictForSchoolAdmin GET /school_admins/{id}/district
DataApi getDistrictForSection GET /sections/{id}/district
DataApi getDistrictForStudent GET /students/{id}/district
DataApi getDistrictForTeacher GET /teachers/{id}/district
DataApi getDistrictForTerm GET /terms/{id}/district
DataApi getDistricts GET /districts
DataApi getSchool GET /schools/{id}
DataApi getSchoolAdmin GET /school_admins/{id}
DataApi getSchoolAdmins GET /school_admins
DataApi getSchoolForSection GET /sections/{id}/school
DataApi getSchoolForStudent GET /students/{id}/school
DataApi getSchoolForTeacher GET /teachers/{id}/school
DataApi getSchools GET /schools
DataApi getSchoolsForSchoolAdmin GET /school_admins/{id}/schools
DataApi getSchoolsForStudent GET /students/{id}/schools
DataApi getSchoolsForTeacher GET /teachers/{id}/schools
DataApi getSection GET /sections/{id}
DataApi getSections GET /sections
DataApi getSectionsForCourse GET /courses/{id}/sections
DataApi getSectionsForSchool GET /schools/{id}/sections
DataApi getSectionsForStudent GET /students/{id}/sections
DataApi getSectionsForTeacher GET /teachers/{id}/sections
DataApi getSectionsForTerm GET /terms/{id}/sections
DataApi getStudent GET /students/{id}
DataApi getStudents GET /students
DataApi getStudentsForContact GET /contacts/{id}/students
DataApi getStudentsForSchool GET /schools/{id}/students
DataApi getStudentsForSection GET /sections/{id}/students
DataApi getStudentsForTeacher GET /teachers/{id}/students
DataApi getTeacher GET /teachers/{id}
DataApi getTeacherForSection GET /sections/{id}/teacher
DataApi getTeachers GET /teachers
DataApi getTeachersForSchool GET /schools/{id}/teachers
DataApi getTeachersForSection GET /sections/{id}/teachers
DataApi getTeachersForStudent GET /students/{id}/teachers
DataApi getTerm GET /terms/{id}
DataApi getTermForSection GET /sections/{id}/term
DataApi getTerms GET /terms
EventsApi getEvent GET /events/{id}
EventsApi getEvents GET /events

Documentation for Models

Documentation for Authorization

Authentication schemes defined for the API:

oauth

Recommendation

It's recommended to create an instance of ApiClient per thread in a multithreaded environment to avoid any potential issues.

Generating the JAR

  1. Git clone Clever's swagger-api repo (https://github.com/Clever/swagger-api)
  2. Install Java 7 or 8, Maven 3.3.3+, and swagger-codegen 2.3.1 via brew
  3. Update the artifactVersion version in clever-java.properties
  4. Re-generate the files:
make generate
  1. Package the JAR:
make build

That will put the jar in: target/client-X.Y.Z.jar

Publishing

To publish this library you need to have a ~/.m2/settings.xml file that looks like this:

<settings>
  <servers>
    <server>
      <id>ossrh</id>
      <username>clever-eng</username>
      <password>SEE-1PASSWORD-FOR-TEAMS</password>
    </server>
  </servers>
</settings>

You can get the password from 1PFT under Sonatype - Maven Repository.

You will also need the PGP private key and passphrase for security@clever.com (ask the Security team for this!). Download the private key and set up as follows:

gpg --import private.security.key

Then run:

make release

You will need to enter the PGP passphrase 5 times during the process.

This will deploy to: https://oss.sonatype.org/content/groups/public/com/clever/client/

The jar will be synced over to the Maven central repository within the next few hours.

Publishing Troubleshooting

If you get an Inappropriate ioctl for device error try the commands here: https://github.com/pstadler/keybase-gpg-github/pull/13/files

If you get an error about repository element was not specified in the POM inside distributionManagement element, you need to add the deployment configuration back into pom.xml, as follows:

Under the <project> element add:

    <distributionManagement>
        <snapshotRepository>
            <id>ossrh</id>
            <url>https://oss.sonatype.org/content/repositories/snapshots</url>
        </snapshotRepository>
    </distributionManagement>

Under <plugins> add:

            <plugin>
                <groupId>org.sonatype.plugins</groupId>
                <artifactId>nexus-staging-maven-plugin</artifactId>
                <version>1.6.7</version>
                <extensions>true</extensions>
                <configuration>
                    <serverId>ossrh</serverId>
                    <nexusUrl>https://oss.sonatype.org/</nexusUrl>
                    <autoReleaseAfterClose>true</autoReleaseAfterClose>
                </configuration>
            </plugin>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-gpg-plugin</artifactId>
                <version>1.5</version>
                <executions>
                    <execution>
                    <id>sign-artifacts</id>
                    <phase>verify</phase>
                    <goals>
                        <goal>sign</goal>
                    </goals>
                    </execution>
                </executions>
            </plugin>