Notice

This library is no longer maintained by Clever, but if you would like to generate your own using the swagger file, it is available at https://github.com/Clever/swagger-api.

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

• BadRequest
• Contact
• ContactObject
• ContactResponse
• ContactsResponse
• Course
• CourseObject
• CourseResponse
• CoursesResponse
• Credentials
• District
• DistrictAdmin
• DistrictAdminObject
• DistrictAdminResponse
• DistrictAdminsResponse
• DistrictObject
• DistrictResponse
• DistrictsResponse
• Event
• EventResponse
• EventsResponse
• InternalError
• Location
• Name
• NotFound
• Principal
• School
• SchoolAdmin
• SchoolAdminObject
• SchoolAdminResponse
• SchoolAdminsResponse
• SchoolObject
• SchoolResponse
• SchoolsResponse
• Section
• SectionObject
• SectionResponse
• SectionsResponse
• Student
• StudentObject
• StudentResponse
• StudentsResponse
• Teacher
• TeacherObject
• TeacherResponse
• TeachersResponse
• Term
• TermObject
• TermResponse
• TermsResponse
• ContactsCreated
• ContactsDeleted
• ContactsUpdated
• CoursesCreated
• CoursesDeleted
• CoursesUpdated
• DistrictadminsCreated
• DistrictadminsDeleted
• DistrictadminsUpdated
• DistrictsCreated
• DistrictsDeleted
• DistrictsUpdated
• SchooladminsCreated
• SchooladminsDeleted
• SchooladminsUpdated
• SchoolsCreated
• SchoolsDeleted
• SchoolsUpdated
• SectionsCreated
• SectionsDeleted
• SectionsUpdated
• StudentsCreated
• StudentsDeleted
• StudentsUpdated
• TeachersCreated
• TeachersDeleted
• TeachersUpdated
• TermsCreated
• TermsDeleted
• TermsUpdated

Documentation for Authorization

Authentication schemes defined for the API:

oauth

• Type: OAuth
• Flow: accessCode
• Authorization URL: https://clever.com/oauth/authorize
• Scopes: N/A

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

5. 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>