Skip to content

This is a simlpe Java Library/API to access the RESTful JSON RCP WebService from Untis

License

Notifications You must be signed in to change notification settings

Airdevelopments/WebUntisAPI-Java

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

22 Commits
 
 
 
 
 
 
 
 

Repository files navigation

WebUntisAPI for Java

This is a simlpe Java Library/API to access the RESTful JSON RCP WebService from Untis.

The jars in the 'builds' folder contain method and class documentation, which should be shown by your IDE after adding it to the classpath.

  1. Installation

  2. Quick Use

    The usage of the library is based on the WebUntisConnection class. Note that it is abstract and must be extended by the user to be used properly. That is because method results of the API differ between customers of Untis and can therefore not be generalized. But I created a class that can be used as a template, it already implements certain methods of the Untis API. Note: these might not work for you instantly and requires further adaption.

    ApplicableWebUntisConnection connection = new ApplicableWebUntisConnection("school-sch", "poly", "username", "password");

    Note: The prefix (2. parameter) of the constructor is the sub-url you see in your browser when logging into the web interface of Untis. For example: https://poly.webuntis.com derives to "poly" as the desired prefix. This can change due to changes by Untis and also may vary between customers. After the creation of a WebUntisConnection instance, you may now call the WebUntisConnection#login() method to connect to the server:

    if(connection.login()) { System.out.println("Login successful!"); }

    Btw: It is recommended to create a single account with a simple password and read only permissions for use in this library, as sensitive data or passwords may be obtained by third parties through decompilation etc!

    One of the implemented methods in the ApplicableWebUntisConnection is the 'getTeachers' method. So let's invoke it. ArrayList<> teachers = connection.getTeachers(); The result can now be processed in any way you want.

    You should always call connection.logout() when you are finished calling methods to free server resources (as stated in the official WebUntis documentation).

  3. Exception Handling

    When calling methods of the library, following exceptions may be thrown:

    WebUntisConnectionErrorException: Thrown when the server responded an error. #getCode(),#getErrorMessage(),#getError() may be used to get detailed information about the error.

    WebUntisConnectionFailureException: Thrown when there has been a problem connecting to the server

    WebUntisConnectionInvalidIDException: Thrown when a result-id does not match up with a request-id (should never happen)

    WebUntisConnectionResultException: Thrown when theres a problem with correctly parsing the result with the JSON library. This might be the case when Untis changed something in their WebAPI

    Code example:

     ApplicableWebUntisConnection connection = new ApplicableWebUntisConnection("school-sch", "poly", "username", "******");
     
     try
     {
     	if(connection.login())
     		System.out.println("Login Successful");
    
     	connection.getSubstitutions("20180212", "20181230");
     	
     	connection.logout();
     }catch(WebUntisConnectionErrorException e)
     {
     	if(e.getError() == WebUntisError.NO_RIGHT_FOR_METHOD)
     	{
     		System.out.println("Permissions need adjustment: " + e.getErrorMessage() + "(" + e.getCode() + ")");
     	}
     	else if(e.getError() == WebUntisError.METHOD_NOT_FOUND)
     	{
     		System.out.println("Seems like the API has changed!");
     	}
     }
    
  4. Implementing own methods

    You might be interested to implement certain methods yourself, because the results differ to my implementation or I did not even implement that method yet. For that you need to extend the WebUntisConnection class:

     public class MyWebUntisConnection extends WebUntisConnection {
    
     public MyWebUntisConnection(String school, String prefix, String user, String password) {
     	super(school, prefix, user, password);
     }
    
     public ArrayList<Student> getStudents()
     {
     	String requestID = Utils.getRandomId(); //generate random id for the request
     	String result = getConnection().executeRequest("{\"id\":\""+requestID+"\",\"method\":\"getStudents\",\"params\":{},\"jsonrpc\":\"2.0\"}");
    
     	JSONObject resultData = preProcess(result, requestID); //handle common issues and catch result as JSONObject
    
     	ArrayList<Student> resultList = new ArrayList<Student>(); //ArrayList to accumulate the resulting student objects
    
     	JSONArray students = resultData.getJSONArray("result"); //grab JSONArray out of server result
     	for(int i = 0; i < students.length(); i++) //iterate through JSONArray
     	{
     		JSONObject student = students.getJSONObject(i); //fetch current student as JSONObject
     		resultList.add(new Student(student.getInt("id"), student.getString("name"), student.getString("foreName"), student.getString("longName"), Gender.valueOf(student.getString("gender").toUpperCase())));
     	}
     	return resultList;
     }
     }
    

    This is the basic structure of a method. You need a requestID by calling Utils.getRandomId(), then you can access the connection by calling getConnection() and execute requests with WebUntisHTTPConnector#executeRequest(String request). The result of an execution should be pre-processed by calling preProcess(String result, String requestID) with the used requestID. This method will handle common exception cases and return a JSONObject that can now be used to gather required information. The rest is up to you, depending on the method and your needs.

  5. Feedback

    If you have any wishes/issues/difficulties, tell me!

  6. License

    You are allowed to use this library to your needs. You can rebuild it for yourself or use one of the pre-builds. Commericial use is also allowed.

About

This is a simlpe Java Library/API to access the RESTful JSON RCP WebService from Untis

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages