- For every layer you can create/delete impersonal API Tokens
- A token can be described by a name and a description
- A token is attached to a certain layer, its rights are derived from
said layerthe token's settings - API Token can only be created and edited by people with :layer_and_below_full and :layer_full permissions
- per Token I can configure whether a specific API token can
- read People on Layer
- read People
on Layer andbelow - read Groups (API to be extended)
- read Events (API to come)
- Events and courses can be filtered by year
- UI matches Mockup more or less
- Last accessed date works
- The token value stays the same when changing permissions, description or name
- A token can not be used anymore once it has been deleted
- When deleting an existing token and then recreating it with the exact same settings, the token value is different
- API should always return JSON, and return the same for parameters style and headers style calls
- The events permission should be called "Events and courses", and in German "Anlässe und Kurse". (Note the term Anlass instead of Event)
- API Documentation should be updated
- All API endpoints work the way they are documented
- Additional requirement / future work: CORS header Access-Control-Allow-Origin should be set on all status 200 API responses
Under all circumstances, using parameters style (.json + token query param) and headers style (X-Token + Accept JSON) requests should give the same responses. However currently, for authenticated but unauthorized parameters style requests, the API returns HTML responses with a login form. The corresponding responses when using headers style requests are a simple JSON object { "email": null, "password": null }
, which is not beautiful but okay if documented.
GET https://pbs.puzzle.ch/groups/3
Accept: application/json
X-Token: soPFCnKNN5HNeLWAP59PYsRBsaExN_RSezyFrRR7jknxC1ofzQ
yields the response:
{
"email": null,
"password": null
}
while
GET https://pbs.puzzle.ch/groups/3.json?token=soPFCnKNN5HNeLWAP59PYsRBsaExN_RSezyFrRR7jknxC1ofzQ
yields the response:
<!DOCTYPE html> <html lang='de'> <head> <meta charset='utf-8'> <title>MiData PBS/MSdS/MSS - Anmelden</title> <meta...
❌ The events permission should be called "Events and courses", and in German "Anlässe und Kurse". (Note the term Anlass instead of Event)
Either this permission should be renamed or a separate permission type for courses should be created.
The exact required parameters for querying the API with a service account token is not documented at https://github.com/hitobito/hitobito/blob/master/doc/development/05_rest_api.md yet.
Add something like the following to the documentation:
There are two possible styles for querying the API with a service account token.
Headers style:
GET https://[hitobito domain]/groups/1 X-Token: [service account token] Accept: application/json
Parameters style:
GET https://[hitobito domain]/groups/1.json?token=[service account token]
Also document which permissions are necessary for which operations (unclear to me was only that the groups permission not only disables access to subgroups, but also to the group to which the token belongs).
The following is a list of all cases where the API does not work as expected, when using service account tokens to access it.
Accessing the root group endpoint /groups
yields the same result as authorization failures regardless of token permissions and even if the token is defined on the root group. In case this is by design, remove the endpoint.
GET https://pbs.puzzle.ch/groups.json?token=wfZPuvZBugipVHeBdWzsbsoLNcasc1xQ-zQKwhyHy5_jAy1hBg
All requests to the /groups/{id}/events/course
endpoint yield the same result as authorization failures regardless of token permissions and even if the token is defined on the root group.
Accessing courses with a token with full permissions:
GET https://pbs.puzzle.ch/groups/1/events/course.json?token=jF4ozjEsSjk12dqFacx9yu4stmbzryy38QyM9PdRNeLfanJwSg
Caution when testing manually: Use an incognito window or make sure that your browser is not logged in to the hitobito instance you are testing. The API currently also reads any active session cookies.
❌ Additional requirement / future work: CORS header Access-Control-Allow-Origin should be set on all status 200 API responses
This is necessary so the API can be used from JavaScript applications in browsers.
Each token could have a list of allowed accessing sources (protocol + (sub)domain + port) for CORS, and the CORS header Access-Control-Allow-Origin is set by the server.
Ok, I went through the list:
1.Root group endpoint does not work: ok, I think the root group access point should always be available, there is no sensitive Information in there anyway.
Thanks for the detailed analysis.