33 lines
2.7 KiB
Markdown
33 lines
2.7 KiB
Markdown
# USOS API notes
|
|
|
|
Checked against USOS API 7.3.1 at `usosapps.put.poznan.pl` on 2026-10-11, by reading `/developers/api/` and by calling the methods that need no key.
|
|
|
|
## Authorization
|
|
|
|
OAuth 1.0a with HMAC-SHA1 signatures, three legs: `services/oauth/request_token`, the user's browser at `services/oauth/authorize`, then `services/oauth/access_token`. Scopes are a USOS extension, passed to `request_token` as `scopes=studies|offline_access`.
|
|
|
|
- `studies` is what the timetable methods require.
|
|
- Without `offline_access` an access token dies after two hours or when the user logs out of USOS. With it the token lives until it is revoked.
|
|
- `services/oauth/revoke_token` revokes the token it is signed with. usoscal calls it on sign-out.
|
|
- A user can also revoke the application in USOS itself. The next refresh then gets HTTP 401, and usoscal drops the stored token and keeps the timetable.
|
|
|
|
Requests are sent as POST with the OAuth parameters in the `Authorization` header and the method parameters in the body, so no token ever appears in a URL.
|
|
|
|
## Timetable
|
|
|
|
`services/tt/user` returns the activities of the signed-in user for `days` days starting at `start`.
|
|
|
|
- `days` is at most 7; 8 is answered with HTTP 400. A semester is therefore about twenty requests, a year about fifty.
|
|
- `start` may be in the past. Weeks of the two previous semesters were returned by the public `services/tt/course_edition`, which shares the same parameters. Dates with no data give an empty list, not an error.
|
|
- No request limits are documented. usoscal waits 200 ms between requests and refreshes each user once a day.
|
|
- `fields` must only name fields that exist for every activity type in the answer. Asking for `related_user_ids` or `slot_number` while the week contains a `classgroup2` activity is answered with HTTP 500. usoscal asks for the class fields and, on a 500, repeats the request with the fields common to all types.
|
|
- `sm_id` identifies a single meeting and is used as the event UID. Activities without it get a UID derived from their course, group, name and start.
|
|
|
|
`services/tt/upcoming_ical` is the export USOS offers itself. It has no date parameters and its documentation says that past events and events far in the future are not included, which is the reason this project exists.
|
|
|
|
## Other methods
|
|
|
|
- `services/users/users` gives lecturer names and titles by id, signed with the consumer key only.
|
|
- `services/geo/building2` gives the postal address of a building, anonymously.
|
|
- `services/terms/search` gives term dates, anonymously. The refresh horizon is the latest `finish_date` among terms shorter than 250 days that are running or start within 60 days, so the exam session after the last class is covered.
|