Zum Inhalt

Documentation for the Alumnii-API

This is the documentation for the REST API version 1.0 of your Alumnii System. The API is a JSON API that is utf-8 encoded. It is probably going to be extended and modified in future versions. We will inform you about upcoming changes. If you feel that either the API or its documentation are missing something please let us know.

Authentication

To authenticate you need an API Key. Please contact your Alumnii representative if you did not get one. API keys are associated to users, a user that is connected to an API key needs to have admin rights in order for the API key to work properly. The API key is passed via the HTTP Authorization header. It should be prefixed by the string Token, note the whitespace between Token and the actual key. If your API key were thisisyourapikey you would for example pass the value Token thisisyourapikey. See the following example request using curl:

curl -X GET https://youralumniisystem.de/api/ -H 'Authorization: Token thisisyourapikey'

Schema

The alumnii API exports a schema (see http://www.coreapi.org/ for an explanation of schemas.) under the endpoint /api/schema/. This should facilitate the use of the alumnii API with the programming language of your choice.

Pagination and Filtering

By default all results in the alumnii API are paginated with 100 entries per page. The fields count, next, previous in a reply should help you to scan through a list of objects. count provides a total object count, next, previous provide the URLs for the next and the previous part of the result set, respectively, and are set to none if no such page exists. The key results contains a list of the actual objects.

Users

The endpoint /api/addressbook/users/ provides access to a user list. Tags and Admin Tags are exported as a list of strings. Individual users can be accessed under /api/addressbook/users/<userid>/. Currently that endpoint does not provide more information then the list of users. Below you find an example for an exported user

{
  "id":2,
  "email":"2@test.test",
  "address":"Frau",
  "address_title":"",
  "first_name":"Melina",
  "family_name":"Musterfrau",
  "former_family_name":"",
  "date_of_birth":null,
  "about_me":"",
  "secondary_email":"",
  "phone_nr":"",
  "mobile_nr":"",
  "webpage":"",
  "company_address":"",
  "street":"Daimlerstr. 25",
  "additional_address_info":"",
  "zip_code":"76185",
  "city":"Karlsruhe",
  "state_region":"",
  "country":"DE",
  "secondary_company_address":"",
  "secondary_street":"",
  "secondary_additional_address_info":"",
  "secondary_zip_code":"",
  "secondary_city":"",
  "secondary_state_region":"",
  "secondary_country":"",
  "modified":"2018-07-11T11:19:15.437214+02:00",
  "receive_newsletter":false,
  "tags":["Mitglied"],
  "admin_tags":[],
  "admin_url":"https://something.alumnii.de/admin/addressbook/profileuser/2/change/",
  "current_company":"Google",
  "current_position":"Projektmanager",
  "grad_year":"Sonstiges",
  "grad_track":"Gymnasium",
  "nak_engagement":[]
}

String fields are never set to null, date fields can be set to null. The three custom fields at the end of export are exemplary for any custom fields that are specific to your data model. The export type of these fields depends on your particular configuration. The admin url allows to link back to the alumnii system. Current company and position are extracted as the most recent position from the person's CV available in the alumnii platform.

It is also possible to filter the user list. Currently two GET parameters are supported for this purpose: email and modified_gte. email tests for an exact match, modified_gte allows to filter users by last modification date. The query api/addressbook/users/?modified_gte=2018-07-01 queries for all users that have been modified after the 1st of July, 2018.