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 |
|
TOKEN_ENDPOINT |
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/events/
- Query Parameters:
end_time_after (string) – end time
end_time_before (string) – end time
limit (integer) – Number of results to return per page.
offset (integer) – The initial index from which to return the results.
ordering (string) – Which field to use when ordering the results.
search (string) – A search term.
start_gte (string) – start time greater than equals (deprecated, use start_time_after instead)
start_lte (string) – start time less than equals (deprecated, use start_time_before instead)
start_time_after (string) – start time
start_time_before (string) – start time
type (integer)
- Status Codes:
200 OK –
- GET /api/events/{id}/
- Parameters:
id (integer) – A unique integer value identifying this event.
- Status Codes:
200 OK –
- GET /api/participations/
Remove information that would not be visible in the web version, i.e. no email and date of birth of participants
- Query Parameters:
end_time_after (string) – end time
end_time_before (string) – end time
event (array) – event id
event_type (array) – event type
limit (integer) – Number of results to return per page.
offset (integer) – The initial index from which to return the results.
shift (array) – shift id
start_gte (string) – start time greater than equals (deprecated, use start_time_after instead)
start_lte (string) – start time less than equals (deprecated, use start_time_before instead)
start_time_after (string) – start time
start_time_before (string) – start time
state (integer) –
0 - requested
1 - confirmed
2 - declined by user
3 - rejected by responsible
4 - getting dispatched
- Status Codes:
200 OK –
- GET /api/participations-userinfo/
- Query Parameters:
end_time_after (string) – end time
end_time_before (string) – end time
event (array) – event id
event_type (array) – event type
limit (integer) – Number of results to return per page.
offset (integer) – The initial index from which to return the results.
shift (array) – shift id
start_gte (string) – start time greater than equals (deprecated, use start_time_after instead)
start_lte (string) – start time less than equals (deprecated, use start_time_before instead)
start_time_after (string) – start time
start_time_before (string) – start time
state (integer) –
0 - requested
1 - confirmed
2 - declined by user
3 - rejected by responsible
4 - getting dispatched
- Status Codes:
200 OK –
- GET /api/participations-userinfo/{id}/
- Parameters:
id (integer) – A unique integer value identifying this abstract participation.
- Status Codes:
200 OK –
- GET /api/participations/{id}/
Remove information that would not be visible in the web version, i.e. no email and date of birth of participants
- Parameters:
id (integer) – A unique integer value identifying this abstract participation.
- Status Codes:
200 OK –
- GET /api/shifts/
- Query Parameters:
end_time_after (string) – end time
end_time_before (string) – end time
limit (integer) – Number of results to return per page.
offset (integer) – The initial index from which to return the results.
ordering (string) – Which field to use when ordering the results.
search (string) – A search term.
start_gte (string) – start time greater than equals (deprecated, use start_time_after instead)
start_lte (string) – start time less than equals (deprecated, use start_time_before instead)
start_time_after (string) – start time
start_time_before (string) – start time
- Status Codes:
200 OK –
- GET /api/shifts/{id}/
- Parameters:
id (integer) – A unique integer value identifying this shift.
- Status Codes:
200 OK –
- GET /api/users/
- Query Parameters:
limit (integer) – Number of results to return per page.
offset (integer) – The initial index from which to return the results.
search (string) – A search term.
- Status Codes:
200 OK –
- GET /api/users/{id}/
- Parameters:
id (integer) – A unique integer value identifying this user profile.
- Status Codes:
200 OK –
- GET /api/users/{user}/participations/
- Parameters:
user (string)
- Query Parameters:
end_time_after (string) – end time
end_time_before (string) – end time
event (array) – event id
event_type (array) – event type
limit (integer) – Number of results to return per page.
offset (integer) – The initial index from which to return the results.
shift (array) – shift id
start_gte (string) – start time greater than equals (deprecated, use start_time_after instead)
start_lte (string) – start time less than equals (deprecated, use start_time_before instead)
start_time_after (string) – start time
start_time_before (string) – start time
state (integer) –
0 - requested
1 - confirmed
2 - declined by user
3 - rejected by responsible
4 - getting dispatched
- Status Codes:
200 OK –
- GET /api/users/{user}/participations/{id}/
- Parameters:
id (integer) – A unique integer value identifying this abstract participation.
user (string)
- Status Codes:
200 OK –
- GET /api/users/me/participations/
- Query Parameters:
end_time_after (string) – end time
end_time_before (string) – end time
event (array) – event id
event_type (array) – event type
limit (integer) – Number of results to return per page.
offset (integer) – The initial index from which to return the results.
shift (array) – shift id
start_gte (string) – start time greater than equals (deprecated, use start_time_after instead)
start_lte (string) – start time less than equals (deprecated, use start_time_before instead)
start_time_after (string) – start time
start_time_before (string) – start time
state (integer) –
0 - requested
1 - confirmed
2 - declined by user
3 - rejected by responsible
4 - getting dispatched
- Status Codes:
200 OK –