API documentation

ephios provides a REST-API built with Django-Rest-Framework.

Auth

You can authenticate against the API using session based authentication or tokens acquired using the OAuth2 flow or manually from the user settings.

Session based authentication

A client can authenticate against the API using session based authentication. This allows to visit API endpoints in the browser and use the API in a similar way as the web interface. Login is required and permissions are checked just like in the web interface. This is the recommended way to access the API from interactive ephios webpages (javascript/AJAX).

Token based authentication

Personal API tokens can be acquired from the user settings page and used in custom applications or scripts to access the API. When creating a token you should provide a helpful description as well as set a fitting expiration date.

ephios uses Scopes to restrict the validity of API tokens to those endpoints that are needed by the application that uses the token. The scope should be as narrow as possible to prevent abuse of the token.

The following scopes are available:

PUBLIC_READ

Öffentliche Daten (bspw. Veranstaltungen und Schichten) lesen

PUBLIC_WRITE

Öffentliche Daten (bspw. Veranstaltungen und Schichten) schreiben

ME_READ

Eigene Daten und Teilnahmen lesen

ME_WRITE

Eigene Daten und Teilnahmen schreiben

CONFIDENTIAL_READ

Vertrauliche Daten (bpsw. fremde Nutzerprofile und Teilnahmen) lesen

CONFIDENTIAL_WRITE

Vertrauliche Daten (bpsw. fremde Nutzerprofile und Teilnahmen) schreiben

In your requests to the API the token must be presented in the Authorization header like this:

Authorization: Bearer <access token>

For example, a curl request to the events endpoint would look like this:

curl -X GET https://your-instance.ephios.de/api/events/ -H 'Authorization: Bearer gvRYPujOFh6iiLbT5Dw'

Permissions are checked based on the tokens scope and the permissions of the user that created the token. For example, if a token with the scope PUBLIC_READ is used, the token can be used to access the events endpoint, but only events that are visible to that user will be returned.

Bemerkung

We plan on integrating API-Keys that are independent of users in the future.

ephios as an OAuth2 provider

ephios can act as an OAuth2 provider which allows third-party applications to obtain API tokens for its users. The API tokens acquired using the OAuth2 flow function just like the manually created ones.

To get started, you need to create an OAuth2 application under „OAuth2 applications“ in the management section of the settings in your ephios instance. Set the client type to confidential, the authorization grant type to „authorization-code“ and the redirect uri to the url of your client application. Note down client id and client secret. You can integrate the OAuth2 flow with a library in your preferred language: https://oauth.net/code/

Set the following values in your third-party application:

CLIENT_ID

client id you created in ephios

CLIENT_SECRET

client secret you created in ephios

AUTHORIZATION_ENDPOINT

https://your-ephios-instance.com/api/oauth/authorize/

TOKEN_ENDPOINT

https://your-ephios-instance.com/api/oauth/token/

With these values, you should be able to initiate the OAuth2 flow, where you also need to specify which scope you want to request from the user. After the user has authorized your application, you will receive an access token that you can use to authenticate against the API endpoints described above.

Endpoints

GET /api/users/me/
Status Codes:
GET /api/events/
Query Parameters:
  • limit (integer) – Number of results to return per page.

  • offset (integer) – The initial index from which to return the results.

  • type (string) – type

  • search (string) – A search term.

  • ordering (string) – Which field to use when ordering the results.

Status Codes:
GET /api/events/{id}/
Parameters:
  • id (string) – A unique integer value identifying this event.

Query Parameters:
  • type (string) – type

  • search (string) – A search term.

  • ordering (string) – Which field to use when ordering the results.

Status Codes:
GET /api/federation/events/

API view that lists all events that are shared with the instance corresponding to the access token.

Query Parameters:
  • limit (integer) – Number of results to return per page.

  • offset (integer) – The initial index from which to return the results.

Status Codes:
GET /api/buildingblocks/
Query Parameters:
  • limit (integer) – Number of results to return per page.

  • offset (integer) – The initial index from which to return the results.

Status Codes:
GET /api/buildingblocks/{id}/
Parameters:
  • id (string) – A unique integer value identifying this building block.

Status Codes:
POST /api/federation/setup/

API view that accepts an InviteCode and creates a FederatedGuest (to start sharing events with that instance).

Status Codes:
DELETE /api/federation/guest/delete/

API view that deletes a FederatedGuest (to stop sharing events with that instance).

Status Codes: