diff --git a/.openapi-generator/FILES b/.openapi-generator/FILES index 144b5180..19759e7c 100644 --- a/.openapi-generator/FILES +++ b/.openapi-generator/FILES @@ -1,6 +1,5 @@ .babelrc .gitignore -.openapi-generator-ignore .travis.yml README.md docs/AnalyticsApi.md @@ -44,8 +43,25 @@ docs/InlineResponse20024Data.md docs/InlineResponse20025.md docs/InlineResponse20026.md docs/InlineResponse20026Data.md +docs/InlineResponse20027.md +docs/InlineResponse20028.md +docs/InlineResponse20029.md +docs/InlineResponse20029Categories.md docs/InlineResponse2003.md +docs/InlineResponse20030.md +docs/InlineResponse20031.md +docs/InlineResponse20032.md +docs/InlineResponse20033.md +docs/InlineResponse20034.md +docs/InlineResponse20035.md +docs/InlineResponse20036.md +docs/InlineResponse20037.md +docs/InlineResponse20038.md +docs/InlineResponse20039.md docs/InlineResponse2004.md +docs/InlineResponse20040.md +docs/InlineResponse20041.md +docs/InlineResponse20042.md docs/InlineResponse2005.md docs/InlineResponse2006.md docs/InlineResponse2007.md @@ -53,6 +69,22 @@ docs/InlineResponse2008.md docs/InlineResponse2009.md docs/Instance.md docs/Lecturer.md +docs/LibCalApi.md +docs/LibcalBooking.md +docs/LibcalCategory.md +docs/LibcalForm.md +docs/LibcalFormField.md +docs/LibcalLocation.md +docs/LibcalLocationBase.md +docs/LibcalPersonalSeatBooking.md +docs/LibcalReserveRequest.md +docs/LibcalReserveRequestBooking.md +docs/LibcalSeat.md +docs/LibcalSeatBooking.md +docs/LibcalSpaceBase.md +docs/LibcalUtilisationSeatSummary.md +docs/LibcalUtilisationSpaceSummary.md +docs/LibcalZone.md docs/Location.md docs/LocationCoordinates.md docs/Map.md @@ -90,6 +122,7 @@ mocha.opts package.json src/ApiClient.js src/api/AnalyticsApi.js +src/api/LibCalApi.js src/api/OAuthApi.js src/api/ResourcesApi.js src/api/RoomBookingsApi.js @@ -137,8 +170,25 @@ src/model/InlineResponse20024Data.js src/model/InlineResponse20025.js src/model/InlineResponse20026.js src/model/InlineResponse20026Data.js +src/model/InlineResponse20027.js +src/model/InlineResponse20028.js +src/model/InlineResponse20029.js +src/model/InlineResponse20029Categories.js src/model/InlineResponse2003.js +src/model/InlineResponse20030.js +src/model/InlineResponse20031.js +src/model/InlineResponse20032.js +src/model/InlineResponse20033.js +src/model/InlineResponse20034.js +src/model/InlineResponse20035.js +src/model/InlineResponse20036.js +src/model/InlineResponse20037.js +src/model/InlineResponse20038.js +src/model/InlineResponse20039.js src/model/InlineResponse2004.js +src/model/InlineResponse20040.js +src/model/InlineResponse20041.js +src/model/InlineResponse20042.js src/model/InlineResponse2005.js src/model/InlineResponse2006.js src/model/InlineResponse2007.js @@ -146,6 +196,21 @@ src/model/InlineResponse2008.js src/model/InlineResponse2009.js src/model/Instance.js src/model/Lecturer.js +src/model/LibcalBooking.js +src/model/LibcalCategory.js +src/model/LibcalForm.js +src/model/LibcalFormField.js +src/model/LibcalLocation.js +src/model/LibcalLocationBase.js +src/model/LibcalPersonalSeatBooking.js +src/model/LibcalReserveRequest.js +src/model/LibcalReserveRequestBooking.js +src/model/LibcalSeat.js +src/model/LibcalSeatBooking.js +src/model/LibcalSpaceBase.js +src/model/LibcalUtilisationSeatSummary.js +src/model/LibcalUtilisationSpaceSummary.js +src/model/LibcalZone.js src/model/Location.js src/model/LocationCoordinates.js src/model/Map.js @@ -173,6 +238,7 @@ src/model/TeachingPeriods.js src/model/Timetable.js src/model/UserData.js test/api/AnalyticsApi.spec.js +test/api/LibCalApi.spec.js test/api/OAuthApi.spec.js test/api/ResourcesApi.spec.js test/api/RoomBookingsApi.spec.js @@ -219,8 +285,25 @@ test/model/InlineResponse20024Data.spec.js test/model/InlineResponse20025.spec.js test/model/InlineResponse20026.spec.js test/model/InlineResponse20026Data.spec.js +test/model/InlineResponse20027.spec.js +test/model/InlineResponse20028.spec.js +test/model/InlineResponse20029.spec.js +test/model/InlineResponse20029Categories.spec.js test/model/InlineResponse2003.spec.js +test/model/InlineResponse20030.spec.js +test/model/InlineResponse20031.spec.js +test/model/InlineResponse20032.spec.js +test/model/InlineResponse20033.spec.js +test/model/InlineResponse20034.spec.js +test/model/InlineResponse20035.spec.js +test/model/InlineResponse20036.spec.js +test/model/InlineResponse20037.spec.js +test/model/InlineResponse20038.spec.js +test/model/InlineResponse20039.spec.js test/model/InlineResponse2004.spec.js +test/model/InlineResponse20040.spec.js +test/model/InlineResponse20041.spec.js +test/model/InlineResponse20042.spec.js test/model/InlineResponse2005.spec.js test/model/InlineResponse2006.spec.js test/model/InlineResponse2007.spec.js @@ -228,6 +311,21 @@ test/model/InlineResponse2008.spec.js test/model/InlineResponse2009.spec.js test/model/Instance.spec.js test/model/Lecturer.spec.js +test/model/LibcalBooking.spec.js +test/model/LibcalCategory.spec.js +test/model/LibcalForm.spec.js +test/model/LibcalFormField.spec.js +test/model/LibcalLocation.spec.js +test/model/LibcalLocationBase.spec.js +test/model/LibcalPersonalSeatBooking.spec.js +test/model/LibcalReserveRequest.spec.js +test/model/LibcalReserveRequestBooking.spec.js +test/model/LibcalSeat.spec.js +test/model/LibcalSeatBooking.spec.js +test/model/LibcalSpaceBase.spec.js +test/model/LibcalUtilisationSeatSummary.spec.js +test/model/LibcalUtilisationSpaceSummary.spec.js +test/model/LibcalZone.spec.js test/model/Location.spec.js test/model/LocationCoordinates.spec.js test/model/Map.spec.js diff --git a/README.md b/README.md index 8c4c0fc8..3c905086 100644 --- a/README.md +++ b/README.md @@ -6,8 +6,8 @@ See the main UCL API Documentation at . This SDK is automatically generated by the [OpenAPI Generator](https://openapi-generator.tech) project: -- API version: 1.0.3 -- Package version: 1.0.3 +- API version: 1.4.2 +- Package version: 1.4.2 - Build package: org.openapitools.codegen.languages.JavascriptClientCodegen ## Installation @@ -95,6 +95,22 @@ Class | Method | HTTP request | Description *uclapi.AnalyticsApi* | [**dashboardApiAnalyticsQuotaGet**](docs/AnalyticsApi.md#dashboardApiAnalyticsQuotaGet) | **GET** /dashboard/api/analytics/quota | Gets the remaining daily quota for a given token *uclapi.AnalyticsApi* | [**dashboardApiAnalyticsServicesGet**](docs/AnalyticsApi.md#dashboardApiAnalyticsServicesGet) | **GET** /dashboard/api/analytics/services | Gets all services and their popularity *uclapi.AnalyticsApi* | [**dashboardApiAnalyticsTotalGet**](docs/AnalyticsApi.md#dashboardApiAnalyticsTotalGet) | **GET** /dashboard/api/analytics/total | Gets the total number of requests made from a given token +*uclapi.LibCalApi* | [**libcalSpaceBookingsGet**](docs/LibCalApi.md#libcalSpaceBookingsGet) | **GET** /libcal/space/bookings | Get all LibCal bookings +*uclapi.LibCalApi* | [**libcalSpaceCancelPost**](docs/LibCalApi.md#libcalSpaceCancelPost) | **POST** /libcal/space/cancel | Cancel one or more LibCal bookings +*uclapi.LibCalApi* | [**libcalSpaceCategoriesGet**](docs/LibCalApi.md#libcalSpaceCategoriesGet) | **GET** /libcal/space/categories | Returns the categories of spaces available in the given location(s) +*uclapi.LibCalApi* | [**libcalSpaceCategoryGet**](docs/LibCalApi.md#libcalSpaceCategoryGet) | **GET** /libcal/space/category | Get all spaces corresponding to the specified categories +*uclapi.LibCalApi* | [**libcalSpaceFormGet**](docs/LibCalApi.md#libcalSpaceFormGet) | **GET** /libcal/space/form | Get all forms (including fields) corresponding to the given LibCal form ID(s) +*uclapi.LibCalApi* | [**libcalSpaceItemGet**](docs/LibCalApi.md#libcalSpaceItemGet) | **GET** /libcal/space/item | Get the spaces corresponding to the given LibCal space ID(s) +*uclapi.LibCalApi* | [**libcalSpaceLocationsGet**](docs/LibCalApi.md#libcalSpaceLocationsGet) | **GET** /libcal/space/locations | Gets all LibCal locations +*uclapi.LibCalApi* | [**libcalSpaceNicknameGet**](docs/LibCalApi.md#libcalSpaceNicknameGet) | **GET** /libcal/space/nickname | Get the nicknames asssigned to certain LibCal bookings +*uclapi.LibCalApi* | [**libcalSpacePersonalBookingsGet**](docs/LibCalApi.md#libcalSpacePersonalBookingsGet) | **GET** /libcal/space/personal_bookings | Get all LibCal bookings +*uclapi.LibCalApi* | [**libcalSpaceQuestionGet**](docs/LibCalApi.md#libcalSpaceQuestionGet) | **GET** /libcal/space/question | Get the questions corresponding to the given LibCal field/question ID(s) +*uclapi.LibCalApi* | [**libcalSpaceReservePost**](docs/LibCalApi.md#libcalSpaceReservePost) | **POST** /libcal/space/reserve | Reserve one or more LibCal spaces/seats +*uclapi.LibCalApi* | [**libcalSpaceSeatGet**](docs/LibCalApi.md#libcalSpaceSeatGet) | **GET** /libcal/space/seat | Get LibCal seat by ID +*uclapi.LibCalApi* | [**libcalSpaceSeatsGet**](docs/LibCalApi.md#libcalSpaceSeatsGet) | **GET** /libcal/space/seats | Get all LibCal seats in a given location +*uclapi.LibCalApi* | [**libcalSpaceUtilizationGet**](docs/LibCalApi.md#libcalSpaceUtilizationGet) | **GET** /libcal/space/utilization | Get utilisation stats for a particular location +*uclapi.LibCalApi* | [**libcalSpaceZoneGet**](docs/LibCalApi.md#libcalSpaceZoneGet) | **GET** /libcal/space/zone | Get LibCal zone by ID +*uclapi.LibCalApi* | [**libcalSpaceZonesGet**](docs/LibCalApi.md#libcalSpaceZonesGet) | **GET** /libcal/space/zones | Get LibCal zones by location *uclapi.OAuthApi* | [**oauthAuthoriseGet**](docs/OAuthApi.md#oauthAuthoriseGet) | **GET** /oauth/authorise | Authorises a user against the API *uclapi.OAuthApi* | [**oauthTokenGet**](docs/OAuthApi.md#oauthTokenGet) | **GET** /oauth/token | A token will be generated which your app can use to get user’s personal data in JSON format from the OAuthSecurity/user/data. *uclapi.OAuthApi* | [**oauthUserDataGet**](docs/OAuthApi.md#oauthUserDataGet) | **GET** /oauth/user/data | Returns personal data on a student at UCL. @@ -165,8 +181,25 @@ Class | Method | HTTP request | Description - [uclapi.InlineResponse20025](docs/InlineResponse20025.md) - [uclapi.InlineResponse20026](docs/InlineResponse20026.md) - [uclapi.InlineResponse20026Data](docs/InlineResponse20026Data.md) + - [uclapi.InlineResponse20027](docs/InlineResponse20027.md) + - [uclapi.InlineResponse20028](docs/InlineResponse20028.md) + - [uclapi.InlineResponse20029](docs/InlineResponse20029.md) + - [uclapi.InlineResponse20029Categories](docs/InlineResponse20029Categories.md) - [uclapi.InlineResponse2003](docs/InlineResponse2003.md) + - [uclapi.InlineResponse20030](docs/InlineResponse20030.md) + - [uclapi.InlineResponse20031](docs/InlineResponse20031.md) + - [uclapi.InlineResponse20032](docs/InlineResponse20032.md) + - [uclapi.InlineResponse20033](docs/InlineResponse20033.md) + - [uclapi.InlineResponse20034](docs/InlineResponse20034.md) + - [uclapi.InlineResponse20035](docs/InlineResponse20035.md) + - [uclapi.InlineResponse20036](docs/InlineResponse20036.md) + - [uclapi.InlineResponse20037](docs/InlineResponse20037.md) + - [uclapi.InlineResponse20038](docs/InlineResponse20038.md) + - [uclapi.InlineResponse20039](docs/InlineResponse20039.md) - [uclapi.InlineResponse2004](docs/InlineResponse2004.md) + - [uclapi.InlineResponse20040](docs/InlineResponse20040.md) + - [uclapi.InlineResponse20041](docs/InlineResponse20041.md) + - [uclapi.InlineResponse20042](docs/InlineResponse20042.md) - [uclapi.InlineResponse2005](docs/InlineResponse2005.md) - [uclapi.InlineResponse2006](docs/InlineResponse2006.md) - [uclapi.InlineResponse2007](docs/InlineResponse2007.md) @@ -174,6 +207,21 @@ Class | Method | HTTP request | Description - [uclapi.InlineResponse2009](docs/InlineResponse2009.md) - [uclapi.Instance](docs/Instance.md) - [uclapi.Lecturer](docs/Lecturer.md) + - [uclapi.LibcalBooking](docs/LibcalBooking.md) + - [uclapi.LibcalCategory](docs/LibcalCategory.md) + - [uclapi.LibcalForm](docs/LibcalForm.md) + - [uclapi.LibcalFormField](docs/LibcalFormField.md) + - [uclapi.LibcalLocation](docs/LibcalLocation.md) + - [uclapi.LibcalLocationBase](docs/LibcalLocationBase.md) + - [uclapi.LibcalPersonalSeatBooking](docs/LibcalPersonalSeatBooking.md) + - [uclapi.LibcalReserveRequest](docs/LibcalReserveRequest.md) + - [uclapi.LibcalReserveRequestBooking](docs/LibcalReserveRequestBooking.md) + - [uclapi.LibcalSeat](docs/LibcalSeat.md) + - [uclapi.LibcalSeatBooking](docs/LibcalSeatBooking.md) + - [uclapi.LibcalSpaceBase](docs/LibcalSpaceBase.md) + - [uclapi.LibcalUtilisationSeatSummary](docs/LibcalUtilisationSeatSummary.md) + - [uclapi.LibcalUtilisationSpaceSummary](docs/LibcalUtilisationSpaceSummary.md) + - [uclapi.LibcalZone](docs/LibcalZone.md) - [uclapi.Location](docs/Location.md) - [uclapi.LocationCoordinates](docs/LocationCoordinates.md) - [uclapi.Map](docs/Map.md) @@ -206,15 +254,26 @@ Class | Method | HTTP request | Description +### ApiToken + + +- **Type**: API key +- **API key parameter name**: token +- **Location**: URL query string + + + ### OAuthSecurity - **Type**: OAuth - **Flow**: accessCode -- **Authorization URL**: /authorise +- **Authorization URL**: /oauth/authorise - **Scopes**: - personal_timetable: read user's timetable - student_number: read user's student number + - libcal_read: read user's LibCal bookings + - libcal_write: reserve/cancel user's LibCal bookings diff --git a/docs/InlineResponse20027.md b/docs/InlineResponse20027.md new file mode 100644 index 00000000..b5340ad2 --- /dev/null +++ b/docs/InlineResponse20027.md @@ -0,0 +1,10 @@ +# uclapi.InlineResponse20027 + +## Properties + +Name | Type | Description | Notes +------------ | ------------- | ------------- | ------------- +**ok** | **Boolean** | | [optional] +**data** | [**[LibcalLocation]**](LibcalLocation.md) | | [optional] + + diff --git a/docs/InlineResponse20028.md b/docs/InlineResponse20028.md new file mode 100644 index 00000000..7733a90e --- /dev/null +++ b/docs/InlineResponse20028.md @@ -0,0 +1,10 @@ +# uclapi.InlineResponse20028 + +## Properties + +Name | Type | Description | Notes +------------ | ------------- | ------------- | ------------- +**ok** | **Boolean** | | [optional] +**categories** | [**[LibcalLocationBase]**](LibcalLocationBase.md) | | [optional] + + diff --git a/docs/InlineResponse20029.md b/docs/InlineResponse20029.md new file mode 100644 index 00000000..bca38842 --- /dev/null +++ b/docs/InlineResponse20029.md @@ -0,0 +1,10 @@ +# uclapi.InlineResponse20029 + +## Properties + +Name | Type | Description | Notes +------------ | ------------- | ------------- | ------------- +**ok** | **Boolean** | | [optional] +**categories** | [**[InlineResponse20029Categories]**](InlineResponse20029Categories.md) | | [optional] + + diff --git a/docs/InlineResponse20029Categories.md b/docs/InlineResponse20029Categories.md new file mode 100644 index 00000000..6310def7 --- /dev/null +++ b/docs/InlineResponse20029Categories.md @@ -0,0 +1,12 @@ +# uclapi.InlineResponse20029Categories + +## Properties + +Name | Type | Description | Notes +------------ | ------------- | ------------- | ------------- +**cid** | **Number** | LibCal category ID denoting a category assigned to a particular space | [optional] +**formid** | **Number** | LibCal booking form ID | [optional] +**_public** | **Number** | 1 if the category of spaces is publicly-bookable, 0 if it is not | [optional] +**items** | **[Number]** | | [optional] + + diff --git a/docs/InlineResponse20030.md b/docs/InlineResponse20030.md new file mode 100644 index 00000000..9859c879 --- /dev/null +++ b/docs/InlineResponse20030.md @@ -0,0 +1,10 @@ +# uclapi.InlineResponse20030 + +## Properties + +Name | Type | Description | Notes +------------ | ------------- | ------------- | ------------- +**ok** | **Boolean** | | [optional] +**forms** | [**[LibcalForm]**](LibcalForm.md) | | [optional] + + diff --git a/docs/InlineResponse20031.md b/docs/InlineResponse20031.md new file mode 100644 index 00000000..b7f14314 --- /dev/null +++ b/docs/InlineResponse20031.md @@ -0,0 +1,10 @@ +# uclapi.InlineResponse20031 + +## Properties + +Name | Type | Description | Notes +------------ | ------------- | ------------- | ------------- +**ok** | **Boolean** | | [optional] +**questions** | [**[LibcalFormField]**](LibcalFormField.md) | | [optional] + + diff --git a/docs/InlineResponse20032.md b/docs/InlineResponse20032.md new file mode 100644 index 00000000..7d77ec57 --- /dev/null +++ b/docs/InlineResponse20032.md @@ -0,0 +1,10 @@ +# uclapi.InlineResponse20032 + +## Properties + +Name | Type | Description | Notes +------------ | ------------- | ------------- | ------------- +**ok** | **Boolean** | | [optional] +**questions** | [**[LibcalSpaceBase]**](LibcalSpaceBase.md) | | [optional] + + diff --git a/docs/InlineResponse20033.md b/docs/InlineResponse20033.md new file mode 100644 index 00000000..60485286 --- /dev/null +++ b/docs/InlineResponse20033.md @@ -0,0 +1,10 @@ +# uclapi.InlineResponse20033 + +## Properties + +Name | Type | Description | Notes +------------ | ------------- | ------------- | ------------- +**ok** | **Boolean** | | [optional] +**categories** | **[Object]** | | [optional] + + diff --git a/docs/InlineResponse20034.md b/docs/InlineResponse20034.md new file mode 100644 index 00000000..cc557be4 --- /dev/null +++ b/docs/InlineResponse20034.md @@ -0,0 +1,10 @@ +# uclapi.InlineResponse20034 + +## Properties + +Name | Type | Description | Notes +------------ | ------------- | ------------- | ------------- +**ok** | **Boolean** | | [optional] +**data** | **Object** | | [optional] + + diff --git a/docs/InlineResponse20035.md b/docs/InlineResponse20035.md new file mode 100644 index 00000000..7c5185a8 --- /dev/null +++ b/docs/InlineResponse20035.md @@ -0,0 +1,10 @@ +# uclapi.InlineResponse20035 + +## Properties + +Name | Type | Description | Notes +------------ | ------------- | ------------- | ------------- +**ok** | **Boolean** | | [optional] +**seats** | [**[LibcalSeat]**](LibcalSeat.md) | | [optional] + + diff --git a/docs/InlineResponse20036.md b/docs/InlineResponse20036.md new file mode 100644 index 00000000..7df3b2df --- /dev/null +++ b/docs/InlineResponse20036.md @@ -0,0 +1,10 @@ +# uclapi.InlineResponse20036 + +## Properties + +Name | Type | Description | Notes +------------ | ------------- | ------------- | ------------- +**ok** | **Boolean** | | [optional] +**seat** | [**LibcalSeat**](LibcalSeat.md) | | [optional] + + diff --git a/docs/InlineResponse20037.md b/docs/InlineResponse20037.md new file mode 100644 index 00000000..7188a13b --- /dev/null +++ b/docs/InlineResponse20037.md @@ -0,0 +1,10 @@ +# uclapi.InlineResponse20037 + +## Properties + +Name | Type | Description | Notes +------------ | ------------- | ------------- | ------------- +**ok** | **Boolean** | | [optional] +**zones** | [**[LibcalZone]**](LibcalZone.md) | | [optional] + + diff --git a/docs/InlineResponse20038.md b/docs/InlineResponse20038.md new file mode 100644 index 00000000..139bd0bb --- /dev/null +++ b/docs/InlineResponse20038.md @@ -0,0 +1,11 @@ +# uclapi.InlineResponse20038 + +## Properties + +Name | Type | Description | Notes +------------ | ------------- | ------------- | ------------- +**ok** | **Boolean** | | [optional] +**error** | **String** | Will be returned if there is an error retrieving the given LibCal space, e.g. if the space ID provided is invalid | [optional] +**zone** | [**LibcalZone**](LibcalZone.md) | | [optional] + + diff --git a/docs/InlineResponse20039.md b/docs/InlineResponse20039.md new file mode 100644 index 00000000..600acba9 --- /dev/null +++ b/docs/InlineResponse20039.md @@ -0,0 +1,10 @@ +# uclapi.InlineResponse20039 + +## Properties + +Name | Type | Description | Notes +------------ | ------------- | ------------- | ------------- +**ok** | **Boolean** | | [optional] +**bookings** | [**[LibcalSeatBooking]**](LibcalSeatBooking.md) | | [optional] + + diff --git a/docs/InlineResponse20040.md b/docs/InlineResponse20040.md new file mode 100644 index 00000000..ce0b2b79 --- /dev/null +++ b/docs/InlineResponse20040.md @@ -0,0 +1,10 @@ +# uclapi.InlineResponse20040 + +## Properties + +Name | Type | Description | Notes +------------ | ------------- | ------------- | ------------- +**ok** | **Boolean** | | [optional] +**bookings** | [**[LibcalPersonalSeatBooking]**](LibcalPersonalSeatBooking.md) | | [optional] + + diff --git a/docs/InlineResponse20041.md b/docs/InlineResponse20041.md new file mode 100644 index 00000000..d2393b02 --- /dev/null +++ b/docs/InlineResponse20041.md @@ -0,0 +1,11 @@ +# uclapi.InlineResponse20041 + +## Properties + +Name | Type | Description | Notes +------------ | ------------- | ------------- | ------------- +**ok** | **Boolean** | | [optional] +**error** | **Object** | Will only be returned if there are errors | [optional] +**bookings** | **Object** | | [optional] + + diff --git a/docs/InlineResponse20042.md b/docs/InlineResponse20042.md new file mode 100644 index 00000000..a938b2b8 --- /dev/null +++ b/docs/InlineResponse20042.md @@ -0,0 +1,10 @@ +# uclapi.InlineResponse20042 + +## Properties + +Name | Type | Description | Notes +------------ | ------------- | ------------- | ------------- +**ok** | **Boolean** | | [optional] +**bookings** | **[Object]** | | [optional] + + diff --git a/docs/LibCalApi.md b/docs/LibCalApi.md new file mode 100644 index 00000000..8028d706 --- /dev/null +++ b/docs/LibCalApi.md @@ -0,0 +1,897 @@ +# uclapi.LibCalApi + +All URIs are relative to *https://uclapi.com* + +Method | HTTP request | Description +------------- | ------------- | ------------- +[**libcalSpaceBookingsGet**](LibCalApi.md#libcalSpaceBookingsGet) | **GET** /libcal/space/bookings | Get all LibCal bookings +[**libcalSpaceCancelPost**](LibCalApi.md#libcalSpaceCancelPost) | **POST** /libcal/space/cancel | Cancel one or more LibCal bookings +[**libcalSpaceCategoriesGet**](LibCalApi.md#libcalSpaceCategoriesGet) | **GET** /libcal/space/categories | Returns the categories of spaces available in the given location(s) +[**libcalSpaceCategoryGet**](LibCalApi.md#libcalSpaceCategoryGet) | **GET** /libcal/space/category | Get all spaces corresponding to the specified categories +[**libcalSpaceFormGet**](LibCalApi.md#libcalSpaceFormGet) | **GET** /libcal/space/form | Get all forms (including fields) corresponding to the given LibCal form ID(s) +[**libcalSpaceItemGet**](LibCalApi.md#libcalSpaceItemGet) | **GET** /libcal/space/item | Get the spaces corresponding to the given LibCal space ID(s) +[**libcalSpaceLocationsGet**](LibCalApi.md#libcalSpaceLocationsGet) | **GET** /libcal/space/locations | Gets all LibCal locations +[**libcalSpaceNicknameGet**](LibCalApi.md#libcalSpaceNicknameGet) | **GET** /libcal/space/nickname | Get the nicknames asssigned to certain LibCal bookings +[**libcalSpacePersonalBookingsGet**](LibCalApi.md#libcalSpacePersonalBookingsGet) | **GET** /libcal/space/personal_bookings | Get all LibCal bookings +[**libcalSpaceQuestionGet**](LibCalApi.md#libcalSpaceQuestionGet) | **GET** /libcal/space/question | Get the questions corresponding to the given LibCal field/question ID(s) +[**libcalSpaceReservePost**](LibCalApi.md#libcalSpaceReservePost) | **POST** /libcal/space/reserve | Reserve one or more LibCal spaces/seats +[**libcalSpaceSeatGet**](LibCalApi.md#libcalSpaceSeatGet) | **GET** /libcal/space/seat | Get LibCal seat by ID +[**libcalSpaceSeatsGet**](LibCalApi.md#libcalSpaceSeatsGet) | **GET** /libcal/space/seats | Get all LibCal seats in a given location +[**libcalSpaceUtilizationGet**](LibCalApi.md#libcalSpaceUtilizationGet) | **GET** /libcal/space/utilization | Get utilisation stats for a particular location +[**libcalSpaceZoneGet**](LibCalApi.md#libcalSpaceZoneGet) | **GET** /libcal/space/zone | Get LibCal zone by ID +[**libcalSpaceZonesGet**](LibCalApi.md#libcalSpaceZonesGet) | **GET** /libcal/space/zones | Get LibCal zones by location + + + +## libcalSpaceBookingsGet + +> InlineResponse20039 libcalSpaceBookingsGet(opts) + +Get all LibCal bookings + +### Example + +```javascript +import uclapi from '@uclapi/sdk'; +let defaultClient = uclapi.ApiClient.instance; +// Configure API key authorization: ApiToken +let ApiToken = defaultClient.authentications['ApiToken']; +ApiToken.apiKey = 'YOUR API KEY'; +// Uncomment the following line to set a prefix for the API key, e.g. "Token" (defaults to null) +//ApiToken.apiKeyPrefix = 'Token'; + +let apiInstance = new uclapi.LibCalApi(); +let opts = { + 'eid': 469,470, // String | Comma delimited list of LibCal space IDs. If specified, will only show bookings for those spaces. + 'seatId': 54435,54436, // String | Comma delimited list of LibCal seat IDs. If specified, will only show bookings for those seats. + 'cid': 3334, // String | Comma delimited list of LibCal category IDs. If specified, will only show bookings for those categories. + 'lid': 702,703, // String | Comma delimited list of LibCal location IDs. If specified, will only show bookings for those locations. + '_date': 2021-06-01, // String | Date in YYYY-MM-DD format. If specified, will only show bookings made on this date. Dates in the past are ignored. Defaults to today's date. + 'days': 3, // Number | Number of days into the future to retrieve bookings from, starting from the data parameter. Defaults to zero. Must be >= 0 and <= 365. + 'limit': 10 // Number | Maximum number of bookings to return. Defaults to 20. The maximum value is 500. +}; +apiInstance.libcalSpaceBookingsGet(opts, (error, data, response) => { + if (error) { + console.error(error); + } else { + console.log('API called successfully. Returned data: ' + data); + } +}); +``` + +### Parameters + + +Name | Type | Description | Notes +------------- | ------------- | ------------- | ------------- + **eid** | **String**| Comma delimited list of LibCal space IDs. If specified, will only show bookings for those spaces. | [optional] + **seatId** | **String**| Comma delimited list of LibCal seat IDs. If specified, will only show bookings for those seats. | [optional] + **cid** | **String**| Comma delimited list of LibCal category IDs. If specified, will only show bookings for those categories. | [optional] + **lid** | **String**| Comma delimited list of LibCal location IDs. If specified, will only show bookings for those locations. | [optional] + **_date** | **String**| Date in YYYY-MM-DD format. If specified, will only show bookings made on this date. Dates in the past are ignored. Defaults to today's date. | [optional] + **days** | **Number**| Number of days into the future to retrieve bookings from, starting from the data parameter. Defaults to zero. Must be >= 0 and <= 365. | [optional] + **limit** | **Number**| Maximum number of bookings to return. Defaults to 20. The maximum value is 500. | [optional] + +### Return type + +[**InlineResponse20039**](InlineResponse20039.md) + +### Authorization + +[ApiToken](../README.md#ApiToken) + +### HTTP request headers + +- **Content-Type**: Not defined +- **Accept**: application/json + + +## libcalSpaceCancelPost + +> InlineResponse20042 libcalSpaceCancelPost(id) + +Cancel one or more LibCal bookings + +### Example + +```javascript +import uclapi from '@uclapi/sdk'; +let defaultClient = uclapi.ApiClient.instance; +// Configure OAuth2 access token for authorization: OAuthSecurity +let OAuthSecurity = defaultClient.authentications['OAuthSecurity']; +OAuthSecurity.accessToken = 'YOUR ACCESS TOKEN'; +// Configure API key authorization: OAuthToken +let OAuthToken = defaultClient.authentications['OAuthToken']; +OAuthToken.apiKey = 'YOUR API KEY'; +// Uncomment the following line to set a prefix for the API key, e.g. "Token" (defaults to null) +//OAuthToken.apiKeyPrefix = 'Token'; + +let apiInstance = new uclapi.LibCalApi(); +let id = cs_loYG4wTz,ab_P1bn30Mn; // String | A comma delimited list of LibCal booking IDs to cancel +apiInstance.libcalSpaceCancelPost(id, (error, data, response) => { + if (error) { + console.error(error); + } else { + console.log('API called successfully. Returned data: ' + data); + } +}); +``` + +### Parameters + + +Name | Type | Description | Notes +------------- | ------------- | ------------- | ------------- + **id** | **String**| A comma delimited list of LibCal booking IDs to cancel | + +### Return type + +[**InlineResponse20042**](InlineResponse20042.md) + +### Authorization + +[OAuthSecurity](../README.md#OAuthSecurity), [OAuthToken](../README.md#OAuthToken) + +### HTTP request headers + +- **Content-Type**: Not defined +- **Accept**: application/json + + +## libcalSpaceCategoriesGet + +> InlineResponse20028 libcalSpaceCategoriesGet(ids) + +Returns the categories of spaces available in the given location(s) + +### Example + +```javascript +import uclapi from '@uclapi/sdk'; +let defaultClient = uclapi.ApiClient.instance; +// Configure API key authorization: ApiToken +let ApiToken = defaultClient.authentications['ApiToken']; +ApiToken.apiKey = 'YOUR API KEY'; +// Uncomment the following line to set a prefix for the API key, e.g. "Token" (defaults to null) +//ApiToken.apiKeyPrefix = 'Token'; + +let apiInstance = new uclapi.LibCalApi(); +let ids = 702,703; // String | Comma delimited list of LibCal location IDs +apiInstance.libcalSpaceCategoriesGet(ids, (error, data, response) => { + if (error) { + console.error(error); + } else { + console.log('API called successfully. Returned data: ' + data); + } +}); +``` + +### Parameters + + +Name | Type | Description | Notes +------------- | ------------- | ------------- | ------------- + **ids** | **String**| Comma delimited list of LibCal location IDs | + +### Return type + +[**InlineResponse20028**](InlineResponse20028.md) + +### Authorization + +[ApiToken](../README.md#ApiToken) + +### HTTP request headers + +- **Content-Type**: Not defined +- **Accept**: application/json + + +## libcalSpaceCategoryGet + +> InlineResponse20029 libcalSpaceCategoryGet(ids, opts) + +Get all spaces corresponding to the specified categories + +### Example + +```javascript +import uclapi from '@uclapi/sdk'; +let defaultClient = uclapi.ApiClient.instance; +// Configure API key authorization: ApiToken +let ApiToken = defaultClient.authentications['ApiToken']; +ApiToken.apiKey = 'YOUR API KEY'; +// Uncomment the following line to set a prefix for the API key, e.g. "Token" (defaults to null) +//ApiToken.apiKeyPrefix = 'Token'; + +let apiInstance = new uclapi.LibCalApi(); +let ids = 3334,3335; // String | Comma delimited list of LibCal category IDs +let opts = { + 'details': 1, // Number | Flag to indicate you want additional details such as terms and conditions. + 'availability': 2021-01-05 // String | Either a single date or a comma delimited list of 2 dates (a start and end date). The keyword 'next' (alone) can also be used to return availability for the next date that this item is available. Setting this parameter also sets the details value to 1. Dates should be in YYYY-MM-DD format. +}; +apiInstance.libcalSpaceCategoryGet(ids, opts, (error, data, response) => { + if (error) { + console.error(error); + } else { + console.log('API called successfully. Returned data: ' + data); + } +}); +``` + +### Parameters + + +Name | Type | Description | Notes +------------- | ------------- | ------------- | ------------- + **ids** | **String**| Comma delimited list of LibCal category IDs | + **details** | **Number**| Flag to indicate you want additional details such as terms and conditions. | [optional] + **availability** | **String**| Either a single date or a comma delimited list of 2 dates (a start and end date). The keyword 'next' (alone) can also be used to return availability for the next date that this item is available. Setting this parameter also sets the details value to 1. Dates should be in YYYY-MM-DD format. | [optional] + +### Return type + +[**InlineResponse20029**](InlineResponse20029.md) + +### Authorization + +[ApiToken](../README.md#ApiToken) + +### HTTP request headers + +- **Content-Type**: Not defined +- **Accept**: application/json + + +## libcalSpaceFormGet + +> InlineResponse20030 libcalSpaceFormGet(ids) + +Get all forms (including fields) corresponding to the given LibCal form ID(s) + +### Example + +```javascript +import uclapi from '@uclapi/sdk'; +let defaultClient = uclapi.ApiClient.instance; +// Configure API key authorization: ApiToken +let ApiToken = defaultClient.authentications['ApiToken']; +ApiToken.apiKey = 'YOUR API KEY'; +// Uncomment the following line to set a prefix for the API key, e.g. "Token" (defaults to null) +//ApiToken.apiKeyPrefix = 'Token'; + +let apiInstance = new uclapi.LibCalApi(); +let ids = 38,62; // String | Comma delimited list of LibCal form IDs +apiInstance.libcalSpaceFormGet(ids, (error, data, response) => { + if (error) { + console.error(error); + } else { + console.log('API called successfully. Returned data: ' + data); + } +}); +``` + +### Parameters + + +Name | Type | Description | Notes +------------- | ------------- | ------------- | ------------- + **ids** | **String**| Comma delimited list of LibCal form IDs | + +### Return type + +[**InlineResponse20030**](InlineResponse20030.md) + +### Authorization + +[ApiToken](../README.md#ApiToken) + +### HTTP request headers + +- **Content-Type**: Not defined +- **Accept**: application/json + + +## libcalSpaceItemGet + +> InlineResponse20032 libcalSpaceItemGet(ids, opts) + +Get the spaces corresponding to the given LibCal space ID(s) + +### Example + +```javascript +import uclapi from '@uclapi/sdk'; +let defaultClient = uclapi.ApiClient.instance; +// Configure API key authorization: ApiToken +let ApiToken = defaultClient.authentications['ApiToken']; +ApiToken.apiKey = 'YOUR API KEY'; +// Uncomment the following line to set a prefix for the API key, e.g. "Token" (defaults to null) +//ApiToken.apiKeyPrefix = 'Token'; + +let apiInstance = new uclapi.LibCalApi(); +let ids = 469,470; // String | Comma delimited list of LibCal space IDs +let opts = { + 'availability': 2021-01-05 // String | Either a single date or a comma delimited list of 2 dates (a start and end date). The keyword 'next' (alone) can also be used to return availability for the next date that this item is available. Setting this parameter also sets the details value to 1. Dates should be in YYYY-MM-DD format. +}; +apiInstance.libcalSpaceItemGet(ids, opts, (error, data, response) => { + if (error) { + console.error(error); + } else { + console.log('API called successfully. Returned data: ' + data); + } +}); +``` + +### Parameters + + +Name | Type | Description | Notes +------------- | ------------- | ------------- | ------------- + **ids** | **String**| Comma delimited list of LibCal space IDs | + **availability** | **String**| Either a single date or a comma delimited list of 2 dates (a start and end date). The keyword 'next' (alone) can also be used to return availability for the next date that this item is available. Setting this parameter also sets the details value to 1. Dates should be in YYYY-MM-DD format. | [optional] + +### Return type + +[**InlineResponse20032**](InlineResponse20032.md) + +### Authorization + +[ApiToken](../README.md#ApiToken) + +### HTTP request headers + +- **Content-Type**: Not defined +- **Accept**: application/json + + +## libcalSpaceLocationsGet + +> InlineResponse20027 libcalSpaceLocationsGet(opts) + +Gets all LibCal locations + +### Example + +```javascript +import uclapi from '@uclapi/sdk'; +let defaultClient = uclapi.ApiClient.instance; +// Configure API key authorization: ApiToken +let ApiToken = defaultClient.authentications['ApiToken']; +ApiToken.apiKey = 'YOUR API KEY'; +// Uncomment the following line to set a prefix for the API key, e.g. "Token" (defaults to null) +//ApiToken.apiKeyPrefix = 'Token'; + +let apiInstance = new uclapi.LibCalApi(); +let opts = { + 'details': 1 // Number | Flag to indicate you want additional details such as terms and conditions. +}; +apiInstance.libcalSpaceLocationsGet(opts, (error, data, response) => { + if (error) { + console.error(error); + } else { + console.log('API called successfully. Returned data: ' + data); + } +}); +``` + +### Parameters + + +Name | Type | Description | Notes +------------- | ------------- | ------------- | ------------- + **details** | **Number**| Flag to indicate you want additional details such as terms and conditions. | [optional] + +### Return type + +[**InlineResponse20027**](InlineResponse20027.md) + +### Authorization + +[ApiToken](../README.md#ApiToken) + +### HTTP request headers + +- **Content-Type**: Not defined +- **Accept**: application/json + + +## libcalSpaceNicknameGet + +> InlineResponse20033 libcalSpaceNicknameGet(ids, opts) + +Get the nicknames asssigned to certain LibCal bookings + +### Example + +```javascript +import uclapi from '@uclapi/sdk'; +let defaultClient = uclapi.ApiClient.instance; +// Configure API key authorization: ApiToken +let ApiToken = defaultClient.authentications['ApiToken']; +ApiToken.apiKey = 'YOUR API KEY'; +// Uncomment the following line to set a prefix for the API key, e.g. "Token" (defaults to null) +//ApiToken.apiKeyPrefix = 'Token'; + +let apiInstance = new uclapi.LibCalApi(); +let ids = 3334,3335; // String | Comma delimited list of LibCal category IDs +let opts = { + 'availability': 2021-01-05 // String | Either a single date or a comma delimited list of 2 dates (a start and end date). The keyword 'next' (alone) can also be used to return availability for the next date that this item is available. Setting this parameter also sets the details value to 1. Dates should be in YYYY-MM-DD format. +}; +apiInstance.libcalSpaceNicknameGet(ids, opts, (error, data, response) => { + if (error) { + console.error(error); + } else { + console.log('API called successfully. Returned data: ' + data); + } +}); +``` + +### Parameters + + +Name | Type | Description | Notes +------------- | ------------- | ------------- | ------------- + **ids** | **String**| Comma delimited list of LibCal category IDs | + **availability** | **String**| Either a single date or a comma delimited list of 2 dates (a start and end date). The keyword 'next' (alone) can also be used to return availability for the next date that this item is available. Setting this parameter also sets the details value to 1. Dates should be in YYYY-MM-DD format. | [optional] + +### Return type + +[**InlineResponse20033**](InlineResponse20033.md) + +### Authorization + +[ApiToken](../README.md#ApiToken) + +### HTTP request headers + +- **Content-Type**: Not defined +- **Accept**: application/json + + +## libcalSpacePersonalBookingsGet + +> InlineResponse20040 libcalSpacePersonalBookingsGet(clientSecret, opts) + +Get all LibCal bookings + +### Example + +```javascript +import uclapi from '@uclapi/sdk'; +let defaultClient = uclapi.ApiClient.instance; +// Configure OAuth2 access token for authorization: OAuthSecurity +let OAuthSecurity = defaultClient.authentications['OAuthSecurity']; +OAuthSecurity.accessToken = 'YOUR ACCESS TOKEN'; +// Configure API key authorization: OAuthToken +let OAuthToken = defaultClient.authentications['OAuthToken']; +OAuthToken.apiKey = 'YOUR API KEY'; +// Uncomment the following line to set a prefix for the API key, e.g. "Token" (defaults to null) +//OAuthToken.apiKeyPrefix = 'Token'; + +let apiInstance = new uclapi.LibCalApi(); +let clientSecret = "clientSecret_example"; // String | Client secret of the authenticating app. +let opts = { + 'eid': 469,470, // String | Comma delimited list of LibCal space IDs. If specified, will only show bookings for those spaces. + 'seatId': 54435,54436, // String | Comma delimited list of LibCal seat IDs. If specified, will only show bookings for those seats. + 'cid': 3334, // String | Comma delimited list of LibCal category IDs. If specified, will only show bookings for those categories. + 'lid': 702,703, // String | Comma delimited list of LibCal location IDs. If specified, will only show bookings for those locations. + 'email': isd_apiteam@ucl.ac.uk, // String | If specified, will only show bookings made with this email address + '_date': 2021-06-01, // String | Date in YYYY-MM-DD format. If specified, will only show bookings made on this date. Dates in the past are ignored. Defaults to today's date. + 'days': 3, // Number | Number of days into the future to retrieve bookings from, starting from the data parameter. Defaults to zero. Must be >= 0 and <= 365. + 'limit': 10, // Number | Maximum number of bookings to return. Defaults to 20. The maximum value is 500. + 'formAnswers': true // Boolean | Whether or not form answers should be returned. Defaults to false. +}; +apiInstance.libcalSpacePersonalBookingsGet(clientSecret, opts, (error, data, response) => { + if (error) { + console.error(error); + } else { + console.log('API called successfully. Returned data: ' + data); + } +}); +``` + +### Parameters + + +Name | Type | Description | Notes +------------- | ------------- | ------------- | ------------- + **clientSecret** | **String**| Client secret of the authenticating app. | + **eid** | **String**| Comma delimited list of LibCal space IDs. If specified, will only show bookings for those spaces. | [optional] + **seatId** | **String**| Comma delimited list of LibCal seat IDs. If specified, will only show bookings for those seats. | [optional] + **cid** | **String**| Comma delimited list of LibCal category IDs. If specified, will only show bookings for those categories. | [optional] + **lid** | **String**| Comma delimited list of LibCal location IDs. If specified, will only show bookings for those locations. | [optional] + **email** | **String**| If specified, will only show bookings made with this email address | [optional] + **_date** | **String**| Date in YYYY-MM-DD format. If specified, will only show bookings made on this date. Dates in the past are ignored. Defaults to today's date. | [optional] + **days** | **Number**| Number of days into the future to retrieve bookings from, starting from the data parameter. Defaults to zero. Must be >= 0 and <= 365. | [optional] + **limit** | **Number**| Maximum number of bookings to return. Defaults to 20. The maximum value is 500. | [optional] + **formAnswers** | **Boolean**| Whether or not form answers should be returned. Defaults to false. | [optional] + +### Return type + +[**InlineResponse20040**](InlineResponse20040.md) + +### Authorization + +[OAuthSecurity](../README.md#OAuthSecurity), [OAuthToken](../README.md#OAuthToken) + +### HTTP request headers + +- **Content-Type**: Not defined +- **Accept**: application/json + + +## libcalSpaceQuestionGet + +> InlineResponse20031 libcalSpaceQuestionGet(ids) + +Get the questions corresponding to the given LibCal field/question ID(s) + +### Example + +```javascript +import uclapi from '@uclapi/sdk'; +let defaultClient = uclapi.ApiClient.instance; +// Configure API key authorization: ApiToken +let ApiToken = defaultClient.authentications['ApiToken']; +ApiToken.apiKey = 'YOUR API KEY'; +// Uncomment the following line to set a prefix for the API key, e.g. "Token" (defaults to null) +//ApiToken.apiKeyPrefix = 'Token'; + +let apiInstance = new uclapi.LibCalApi(); +let ids = 43,8; // String | Comma delimited list of LibCal field/question IDs +apiInstance.libcalSpaceQuestionGet(ids, (error, data, response) => { + if (error) { + console.error(error); + } else { + console.log('API called successfully. Returned data: ' + data); + } +}); +``` + +### Parameters + + +Name | Type | Description | Notes +------------- | ------------- | ------------- | ------------- + **ids** | **String**| Comma delimited list of LibCal field/question IDs | + +### Return type + +[**InlineResponse20031**](InlineResponse20031.md) + +### Authorization + +[ApiToken](../README.md#ApiToken) + +### HTTP request headers + +- **Content-Type**: Not defined +- **Accept**: application/json + + +## libcalSpaceReservePost + +> InlineResponse20041 libcalSpaceReservePost(libcalReserveRequest) + +Reserve one or more LibCal spaces/seats + +### Example + +```javascript +import uclapi from '@uclapi/sdk'; +let defaultClient = uclapi.ApiClient.instance; +// Configure OAuth2 access token for authorization: OAuthSecurity +let OAuthSecurity = defaultClient.authentications['OAuthSecurity']; +OAuthSecurity.accessToken = 'YOUR ACCESS TOKEN'; +// Configure API key authorization: OAuthToken +let OAuthToken = defaultClient.authentications['OAuthToken']; +OAuthToken.apiKey = 'YOUR API KEY'; +// Uncomment the following line to set a prefix for the API key, e.g. "Token" (defaults to null) +//OAuthToken.apiKeyPrefix = 'Token'; + +let apiInstance = new uclapi.LibCalApi(); +let libcalReserveRequest = new uclapi.LibcalReserveRequest(); // LibcalReserveRequest | +apiInstance.libcalSpaceReservePost(libcalReserveRequest, (error, data, response) => { + if (error) { + console.error(error); + } else { + console.log('API called successfully. Returned data: ' + data); + } +}); +``` + +### Parameters + + +Name | Type | Description | Notes +------------- | ------------- | ------------- | ------------- + **libcalReserveRequest** | [**LibcalReserveRequest**](LibcalReserveRequest.md)| | + +### Return type + +[**InlineResponse20041**](InlineResponse20041.md) + +### Authorization + +[OAuthSecurity](../README.md#OAuthSecurity), [OAuthToken](../README.md#OAuthToken) + +### HTTP request headers + +- **Content-Type**: application/json +- **Accept**: application/json + + +## libcalSpaceSeatGet + +> InlineResponse20036 libcalSpaceSeatGet(ids, opts) + +Get LibCal seat by ID + +### Example + +```javascript +import uclapi from '@uclapi/sdk'; +let defaultClient = uclapi.ApiClient.instance; +// Configure API key authorization: ApiToken +let ApiToken = defaultClient.authentications['ApiToken']; +ApiToken.apiKey = 'YOUR API KEY'; +// Uncomment the following line to set a prefix for the API key, e.g. "Token" (defaults to null) +//ApiToken.apiKeyPrefix = 'Token'; + +let apiInstance = new uclapi.LibCalApi(); +let ids = 3334,3335; // String | Comma delimited list of LibCal category IDs +let opts = { + 'availability': 2021-01-05 // String | Either a single date or a comma delimited list of 2 dates (a start and end date). The keyword 'next' (alone) can also be used to return availability for the next date that this item is available. Setting this parameter also sets the details value to 1. Dates should be in YYYY-MM-DD format. +}; +apiInstance.libcalSpaceSeatGet(ids, opts, (error, data, response) => { + if (error) { + console.error(error); + } else { + console.log('API called successfully. Returned data: ' + data); + } +}); +``` + +### Parameters + + +Name | Type | Description | Notes +------------- | ------------- | ------------- | ------------- + **ids** | **String**| Comma delimited list of LibCal category IDs | + **availability** | **String**| Either a single date or a comma delimited list of 2 dates (a start and end date). The keyword 'next' (alone) can also be used to return availability for the next date that this item is available. Setting this parameter also sets the details value to 1. Dates should be in YYYY-MM-DD format. | [optional] + +### Return type + +[**InlineResponse20036**](InlineResponse20036.md) + +### Authorization + +[ApiToken](../README.md#ApiToken) + +### HTTP request headers + +- **Content-Type**: Not defined +- **Accept**: application/json + + +## libcalSpaceSeatsGet + +> InlineResponse20035 libcalSpaceSeatsGet(ids, opts) + +Get all LibCal seats in a given location + +### Example + +```javascript +import uclapi from '@uclapi/sdk'; +let defaultClient = uclapi.ApiClient.instance; +// Configure API key authorization: ApiToken +let ApiToken = defaultClient.authentications['ApiToken']; +ApiToken.apiKey = 'YOUR API KEY'; +// Uncomment the following line to set a prefix for the API key, e.g. "Token" (defaults to null) +//ApiToken.apiKeyPrefix = 'Token'; + +let apiInstance = new uclapi.LibCalApi(); +let ids = 702; // String | A single LibCal location ID +let opts = { + 'spaceId': 1791, // String | If specified, only return data for this space + 'categoryId': 3334, // String | If specified, will only return data for that category + 'seatId': 54435, // String | Show only the seat with this ID. If this is specified, spaceId, categoryId, and zoneId will be ignored. + 'accessibleOnly': false, // Boolean | Return only acessible seats (i.e. seats with height-adjustable furniture). + 'availability': 2021-01-05, // String | Either a single date or a comma delimited list of 2 dates (a start and end date). The keyword 'next' (alone) can also be used to return availability for the next date that this item is available. Setting this parameter also sets the details value to 1. Dates should be in YYYY-MM-DD format. + 'pageIndex': 0, // Number | For pagination purposes, this specifies the page to be retrieved. Starts at 0 for the first page. + 'pageSize': 10 // Number | For pagination purposes, this specifies the number of results per page. Must be >= 1 and <= 100. The default is 20. +}; +apiInstance.libcalSpaceSeatsGet(ids, opts, (error, data, response) => { + if (error) { + console.error(error); + } else { + console.log('API called successfully. Returned data: ' + data); + } +}); +``` + +### Parameters + + +Name | Type | Description | Notes +------------- | ------------- | ------------- | ------------- + **ids** | **String**| A single LibCal location ID | + **spaceId** | **String**| If specified, only return data for this space | [optional] + **categoryId** | **String**| If specified, will only return data for that category | [optional] + **seatId** | **String**| Show only the seat with this ID. If this is specified, spaceId, categoryId, and zoneId will be ignored. | [optional] + **accessibleOnly** | **Boolean**| Return only acessible seats (i.e. seats with height-adjustable furniture). | [optional] + **availability** | **String**| Either a single date or a comma delimited list of 2 dates (a start and end date). The keyword 'next' (alone) can also be used to return availability for the next date that this item is available. Setting this parameter also sets the details value to 1. Dates should be in YYYY-MM-DD format. | [optional] + **pageIndex** | **Number**| For pagination purposes, this specifies the page to be retrieved. Starts at 0 for the first page. | [optional] + **pageSize** | **Number**| For pagination purposes, this specifies the number of results per page. Must be >= 1 and <= 100. The default is 20. | [optional] + +### Return type + +[**InlineResponse20035**](InlineResponse20035.md) + +### Authorization + +[ApiToken](../README.md#ApiToken) + +### HTTP request headers + +- **Content-Type**: Not defined +- **Accept**: application/json + + +## libcalSpaceUtilizationGet + +> InlineResponse20034 libcalSpaceUtilizationGet(ids, opts) + +Get utilisation stats for a particular location + +Optionally filter by categoryId and zoneId + +### Example + +```javascript +import uclapi from '@uclapi/sdk'; +let defaultClient = uclapi.ApiClient.instance; +// Configure API key authorization: ApiToken +let ApiToken = defaultClient.authentications['ApiToken']; +ApiToken.apiKey = 'YOUR API KEY'; +// Uncomment the following line to set a prefix for the API key, e.g. "Token" (defaults to null) +//ApiToken.apiKeyPrefix = 'Token'; + +let apiInstance = new uclapi.LibCalApi(); +let ids = 702; // String | A single LibCal location ID +let opts = { + 'categoryId': 3334, // String | If specified, will only return data for that category + 'zoneId': 87 // String | If specified, will only return data for that zone +}; +apiInstance.libcalSpaceUtilizationGet(ids, opts, (error, data, response) => { + if (error) { + console.error(error); + } else { + console.log('API called successfully. Returned data: ' + data); + } +}); +``` + +### Parameters + + +Name | Type | Description | Notes +------------- | ------------- | ------------- | ------------- + **ids** | **String**| A single LibCal location ID | + **categoryId** | **String**| If specified, will only return data for that category | [optional] + **zoneId** | **String**| If specified, will only return data for that zone | [optional] + +### Return type + +[**InlineResponse20034**](InlineResponse20034.md) + +### Authorization + +[ApiToken](../README.md#ApiToken) + +### HTTP request headers + +- **Content-Type**: Not defined +- **Accept**: application/json + + +## libcalSpaceZoneGet + +> InlineResponse20038 libcalSpaceZoneGet(opts) + +Get LibCal zone by ID + +### Example + +```javascript +import uclapi from '@uclapi/sdk'; +let defaultClient = uclapi.ApiClient.instance; +// Configure API key authorization: ApiToken +let ApiToken = defaultClient.authentications['ApiToken']; +ApiToken.apiKey = 'YOUR API KEY'; +// Uncomment the following line to set a prefix for the API key, e.g. "Token" (defaults to null) +//ApiToken.apiKeyPrefix = 'Token'; + +let apiInstance = new uclapi.LibCalApi(); +let opts = { + 'zoneId': 87 // String | If specified, will only return data for that zone +}; +apiInstance.libcalSpaceZoneGet(opts, (error, data, response) => { + if (error) { + console.error(error); + } else { + console.log('API called successfully. Returned data: ' + data); + } +}); +``` + +### Parameters + + +Name | Type | Description | Notes +------------- | ------------- | ------------- | ------------- + **zoneId** | **String**| If specified, will only return data for that zone | [optional] + +### Return type + +[**InlineResponse20038**](InlineResponse20038.md) + +### Authorization + +[ApiToken](../README.md#ApiToken) + +### HTTP request headers + +- **Content-Type**: Not defined +- **Accept**: application/json + + +## libcalSpaceZonesGet + +> InlineResponse20037 libcalSpaceZonesGet(ids) + +Get LibCal zones by location + +### Example + +```javascript +import uclapi from '@uclapi/sdk'; +let defaultClient = uclapi.ApiClient.instance; +// Configure API key authorization: ApiToken +let ApiToken = defaultClient.authentications['ApiToken']; +ApiToken.apiKey = 'YOUR API KEY'; +// Uncomment the following line to set a prefix for the API key, e.g. "Token" (defaults to null) +//ApiToken.apiKeyPrefix = 'Token'; + +let apiInstance = new uclapi.LibCalApi(); +let ids = 702; // String | A single LibCal location ID +apiInstance.libcalSpaceZonesGet(ids, (error, data, response) => { + if (error) { + console.error(error); + } else { + console.log('API called successfully. Returned data: ' + data); + } +}); +``` + +### Parameters + + +Name | Type | Description | Notes +------------- | ------------- | ------------- | ------------- + **ids** | **String**| A single LibCal location ID | + +### Return type + +[**InlineResponse20037**](InlineResponse20037.md) + +### Authorization + +[ApiToken](../README.md#ApiToken) + +### HTTP request headers + +- **Content-Type**: Not defined +- **Accept**: application/json + diff --git a/docs/LibcalBooking.md b/docs/LibcalBooking.md new file mode 100644 index 00000000..22dfae97 --- /dev/null +++ b/docs/LibcalBooking.md @@ -0,0 +1,13 @@ +# uclapi.LibcalBooking + +## Properties + +Name | Type | Description | Notes +------------ | ------------- | ------------- | ------------- +**nickname** | **String** | Nickname assigned to this LibCal booking | [optional] +**start** | **String** | Timestamp (in ISO 8601 format) at which this LibCal booking starts | [optional] +**end** | **String** | Timestamp (in ISO 8601 format) at which this LibCal booking ends | [optional] +**created** | **String** | Timestamp (in ISO 8601 format) denoting when this LibCal booking was created | [optional] +**bookingId** | **String** | ID assigned to this LibCal booking | [optional] + + diff --git a/docs/LibcalCategory.md b/docs/LibcalCategory.md new file mode 100644 index 00000000..6dc13143 --- /dev/null +++ b/docs/LibcalCategory.md @@ -0,0 +1,12 @@ +# uclapi.LibcalCategory + +## Properties + +Name | Type | Description | Notes +------------ | ------------- | ------------- | ------------- +**cid** | **Number** | LibCal category ID denoting a category assigned to a particular space | [optional] +**formid** | **Number** | LibCal booking form ID | [optional] +**name** | **String** | Name of the category | [optional] +**_public** | **Number** | 1 if the category of spaces is publicly-bookable, 0 if it is not | [optional] + + diff --git a/docs/LibcalForm.md b/docs/LibcalForm.md new file mode 100644 index 00000000..e390cb9c --- /dev/null +++ b/docs/LibcalForm.md @@ -0,0 +1,11 @@ +# uclapi.LibcalForm + +## Properties + +Name | Type | Description | Notes +------------ | ------------- | ------------- | ------------- +**id** | **Number** | LibCal booking form ID | [optional] +**name** | **String** | Name of the LibCal booking form | [optional] +**fields** | [**[LibcalFormField]**](LibcalFormField.md) | | [optional] + + diff --git a/docs/LibcalFormField.md b/docs/LibcalFormField.md new file mode 100644 index 00000000..0004e84a --- /dev/null +++ b/docs/LibcalFormField.md @@ -0,0 +1,12 @@ +# uclapi.LibcalFormField + +## Properties + +Name | Type | Description | Notes +------------ | ------------- | ------------- | ------------- +**label** | **String** | Label for the field in the LibCal booking form | [optional] +**type** | **String** | Field type for the field in the LibCal booking form. Examples of field types include 'string' and 'dropdown'. | [optional] +**required** | **Boolean** | Whether the field in the LibCal booking form is required (true) or optional (false) | [optional] +**options** | **[String]** | Array of options that will be provided if the field type is dropdown | [optional] + + diff --git a/docs/LibcalLocation.md b/docs/LibcalLocation.md new file mode 100644 index 00000000..043c74cf --- /dev/null +++ b/docs/LibcalLocation.md @@ -0,0 +1,12 @@ +# uclapi.LibcalLocation + +## Properties + +Name | Type | Description | Notes +------------ | ------------- | ------------- | ------------- +**_public** | **Number** | 1 if the location is publicly-bookable, 0 if it is not | [optional] +**terms** | **String** | Additional details about the location, such as terms & conditions. May include HTML. | [optional] +**lid** | **Number** | ID for the LibCal location in question | [optional] +**name** | **String** | Name of the LibCal location in question | [optional] + + diff --git a/docs/LibcalLocationBase.md b/docs/LibcalLocationBase.md new file mode 100644 index 00000000..23057240 --- /dev/null +++ b/docs/LibcalLocationBase.md @@ -0,0 +1,10 @@ +# uclapi.LibcalLocationBase + +## Properties + +Name | Type | Description | Notes +------------ | ------------- | ------------- | ------------- +**lid** | **Number** | ID for the LibCal location in question | [optional] +**name** | **String** | Name of the LibCal location in question | [optional] + + diff --git a/docs/LibcalPersonalSeatBooking.md b/docs/LibcalPersonalSeatBooking.md new file mode 100644 index 00000000..520541fd --- /dev/null +++ b/docs/LibcalPersonalSeatBooking.md @@ -0,0 +1,26 @@ +# uclapi.LibcalPersonalSeatBooking + +## Properties + +Name | Type | Description | Notes +------------ | ------------- | ------------- | ------------- +**bookId** | **String** | ID assigned to this LibCal booking | [optional] +**firstName** | **String** | First name of the user who booked this | [optional] +**lastName** | **String** | Last name of the user who booked this | [optional] +**email** | **String** | Email address of the user who booked this | [optional] +**checkInCode** | **String** | Email address of the user who booked this | [optional] +**eid** | **Number** | ID of this LibCal space | [optional] +**cid** | **Number** | LibCal category ID denoting a category assigned to a particular space | [optional] +**lid** | **Number** | LibCal Location ID | [optional] +**fromDate** | **String** | Timestamp (in ISO 8601 format) at which this LibCal booking starts | [optional] +**toDate** | **String** | Timestamp (in ISO 8601 format) at which this LibCal booking ends | [optional] +**created** | **String** | Timestamp (in ISO 8601 format) denoting when this LibCal booking was created | [optional] +**status** | **String** | Status of this LibCal booking | [optional] +**locationName** | **String** | Name of the LibCal location in question | [optional] +**categoryName** | **String** | Name of the category | [optional] +**itemName** | **String** | Name of this LibCal space | [optional] +**seatId** | **Number** | LibCal seat ID | [optional] +**seatName** | **String** | Name of the LibCal seat | [optional] +**cancelled** | **String** | Timestamp (in ISO 8601 format) at which this LibCal booking was cancelled, if applicable | [optional] + + diff --git a/docs/LibcalReserveRequest.md b/docs/LibcalReserveRequest.md new file mode 100644 index 00000000..6edcbcf8 --- /dev/null +++ b/docs/LibcalReserveRequest.md @@ -0,0 +1,12 @@ +# uclapi.LibcalReserveRequest + +## Properties + +Name | Type | Description | Notes +------------ | ------------- | ------------- | ------------- +**start** | **String** | Timestamp (in ISO 8601 format) at which this LibCal booking starts | +**test** | **Number** | Whether or not this is a test booking. If set, the system will process the booking but will not actually make it. This is useful during development. | +**nickname** | **String** | If the space to be booked has a nickname, then the nickname must be supplied here. | [optional] +**bookings** | [**[LibcalReserveRequestBooking]**](LibcalReserveRequestBooking.md) | | [optional] + + diff --git a/docs/LibcalReserveRequestBooking.md b/docs/LibcalReserveRequestBooking.md new file mode 100644 index 00000000..5e952cdf --- /dev/null +++ b/docs/LibcalReserveRequestBooking.md @@ -0,0 +1,11 @@ +# uclapi.LibcalReserveRequestBooking + +## Properties + +Name | Type | Description | Notes +------------ | ------------- | ------------- | ------------- +**id** | **Number** | ID of this LibCal space | +**to** | **String** | Timestamp (in ISO 8601 format) at which this LibCal booking ends | +**seatId** | **Number** | LibCal seat ID | [optional] + + diff --git a/docs/LibcalSeat.md b/docs/LibcalSeat.md new file mode 100644 index 00000000..04d911b0 --- /dev/null +++ b/docs/LibcalSeat.md @@ -0,0 +1,15 @@ +# uclapi.LibcalSeat + +## Properties + +Name | Type | Description | Notes +------------ | ------------- | ------------- | ------------- +**id** | **Number** | LibCal seat ID | [optional] +**name** | **String** | Name of the LibCal seat | [optional] +**description** | **String** | Description provided for the LibCal seat. May contain HTML | [optional] +**isAccessible** | **Boolean** | Whether the seat is height-adjustable and hence accessible by the differently-abled | [optional] +**isPowered** | **Boolean** | Whether a power socket is available at the seat | [optional] +**image** | **String** | A URL pointing to an image of the seat. If none is available, an empty string will be returned | [optional] +**status** | **Boolean** | The current status of the seat | [optional] + + diff --git a/docs/LibcalSeatBooking.md b/docs/LibcalSeatBooking.md new file mode 100644 index 00000000..2d50b09c --- /dev/null +++ b/docs/LibcalSeatBooking.md @@ -0,0 +1,21 @@ +# uclapi.LibcalSeatBooking + +## Properties + +Name | Type | Description | Notes +------------ | ------------- | ------------- | ------------- +**eid** | **Number** | ID of this LibCal space | [optional] +**cid** | **Number** | LibCal category ID denoting a category assigned to a particular space | [optional] +**lid** | **Number** | LibCal Location ID | [optional] +**fromDate** | **String** | Timestamp (in ISO 8601 format) at which this LibCal booking starts | [optional] +**toDate** | **String** | Timestamp (in ISO 8601 format) at which this LibCal booking ends | [optional] +**created** | **String** | Timestamp (in ISO 8601 format) denoting when this LibCal booking was created | [optional] +**status** | **String** | Status of this LibCal booking | [optional] +**locationName** | **String** | Name of the LibCal location in question | [optional] +**categoryName** | **String** | Name of the category | [optional] +**itemName** | **String** | Name of this LibCal space | [optional] +**seatId** | **Number** | LibCal seat ID | [optional] +**seatName** | **String** | Name of the LibCal seat | [optional] +**cancelled** | **String** | Timestamp (in ISO 8601 format) at which this LibCal booking was cancelled, if applicable | [optional] + + diff --git a/docs/LibcalSpaceBase.md b/docs/LibcalSpaceBase.md new file mode 100644 index 00000000..7db4d521 --- /dev/null +++ b/docs/LibcalSpaceBase.md @@ -0,0 +1,14 @@ +# uclapi.LibcalSpaceBase + +## Properties + +Name | Type | Description | Notes +------------ | ------------- | ------------- | ------------- +**id** | **Number** | ID of this LibCal space | [optional] +**name** | **String** | Name of this LibCal space | [optional] +**description** | **String** | Description of this LibCal space | [optional] +**image** | **String** | URL pointing to an image depicting this LibCal space | [optional] +**capacity** | **Number** | Maximum number of persons this LibCal space can accommodate | [optional] +**formid** | **Number** | ID of the form associated with this LibCal space | [optional] + + diff --git a/docs/LibcalUtilisationSeatSummary.md b/docs/LibcalUtilisationSeatSummary.md new file mode 100644 index 00000000..7c7d773c --- /dev/null +++ b/docs/LibcalUtilisationSeatSummary.md @@ -0,0 +1,11 @@ +# uclapi.LibcalUtilisationSeatSummary + +## Properties + +Name | Type | Description | Notes +------------ | ------------- | ------------- | ------------- +**active** | **Number** | Number of active LibCal bookings of seats | [optional] +**bookableCount** | **Number** | Number of LibCal seats available to be booked | [optional] +**total** | **Number** | Total number of LibCal seats in the location | [optional] + + diff --git a/docs/LibcalUtilisationSpaceSummary.md b/docs/LibcalUtilisationSpaceSummary.md new file mode 100644 index 00000000..095bf4b4 --- /dev/null +++ b/docs/LibcalUtilisationSpaceSummary.md @@ -0,0 +1,11 @@ +# uclapi.LibcalUtilisationSpaceSummary + +## Properties + +Name | Type | Description | Notes +------------ | ------------- | ------------- | ------------- +**active** | **Number** | Number of active LibCal bookings of spaces | [optional] +**bookableCount** | **Number** | Number of LibCal spaces available to be booked | [optional] +**total** | **Number** | Total number of LibCal spaces in the location | [optional] + + diff --git a/docs/LibcalZone.md b/docs/LibcalZone.md new file mode 100644 index 00000000..75529779 --- /dev/null +++ b/docs/LibcalZone.md @@ -0,0 +1,10 @@ +# uclapi.LibcalZone + +## Properties + +Name | Type | Description | Notes +------------ | ------------- | ------------- | ------------- +**id** | **Number** | LibCal Zone ID | [optional] +**name** | **String** | Name of the LibCal zone | [optional] + + diff --git a/openapitools.json b/openapitools.json index 6dff05ce..a00efaee 100644 --- a/openapitools.json +++ b/openapitools.json @@ -11,7 +11,7 @@ "templateDir": "#{cwd}/sdk-templates", "additionalProperties": { "projectName": "@uclapi/sdk", - "projectVersion": "1.0.3", + "projectVersion": "1.4.2", "moduleName": "uclapi", "projectDescription": "UCL API JavaScript SDK" } diff --git a/package.json b/package.json index 9786808b..f0d35c87 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@uclapi/sdk", - "version": "1.0.3", + "version": "1.4.2", "description": "UCL API JavaScript SDK", "license": "MIT License", "main": "dist/index.js", diff --git a/src/ApiClient.js b/src/ApiClient.js index 26209636..dc2769d7 100644 --- a/src/ApiClient.js +++ b/src/ApiClient.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -17,7 +17,7 @@ import querystring from "querystring"; /** * @module ApiClient -* @version 1.0.3 +* @version 1.4.2 */ /** @@ -41,6 +41,7 @@ class ApiClient { * @type {Array.} */ this.authentications = { + 'ApiToken': {type: 'apiKey', 'in': 'query', name: 'token'}, 'OAuthSecurity': {type: 'oauth2'}, 'OAuthToken': {type: 'apiKey', 'in': 'query', name: 'token'} } diff --git a/src/api/AnalyticsApi.js b/src/api/AnalyticsApi.js index 60f42ee9..81c08b08 100644 --- a/src/api/AnalyticsApi.js +++ b/src/api/AnalyticsApi.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -24,7 +24,7 @@ import InlineResponse20026 from '../model/InlineResponse20026'; /** * Analytics service. * @module api/AnalyticsApi -* @version 1.0.3 +* @version 1.4.2 */ export default class AnalyticsApi { diff --git a/src/api/LibCalApi.js b/src/api/LibCalApi.js new file mode 100644 index 00000000..432db1d0 --- /dev/null +++ b/src/api/LibCalApi.js @@ -0,0 +1,793 @@ +/** + * UCL API + * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` + * + * The version of the OpenAPI document: 1.4.2 + * Contact: isd.apiteam@ucl.ac.uk + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + * + */ + + +import ApiClient from "../ApiClient"; +import Error from '../model/Error'; +import InlineResponse20027 from '../model/InlineResponse20027'; +import InlineResponse20028 from '../model/InlineResponse20028'; +import InlineResponse20029 from '../model/InlineResponse20029'; +import InlineResponse20030 from '../model/InlineResponse20030'; +import InlineResponse20031 from '../model/InlineResponse20031'; +import InlineResponse20032 from '../model/InlineResponse20032'; +import InlineResponse20033 from '../model/InlineResponse20033'; +import InlineResponse20034 from '../model/InlineResponse20034'; +import InlineResponse20035 from '../model/InlineResponse20035'; +import InlineResponse20036 from '../model/InlineResponse20036'; +import InlineResponse20037 from '../model/InlineResponse20037'; +import InlineResponse20038 from '../model/InlineResponse20038'; +import InlineResponse20039 from '../model/InlineResponse20039'; +import InlineResponse20040 from '../model/InlineResponse20040'; +import InlineResponse20041 from '../model/InlineResponse20041'; +import InlineResponse20042 from '../model/InlineResponse20042'; +import LibcalReserveRequest from '../model/LibcalReserveRequest'; + +/** +* LibCal service. +* @module api/LibCalApi +* @version 1.4.2 +*/ +export default class LibCalApi { + + /** + * Constructs a new LibCalApi. + * @alias module:api/LibCalApi + * @class + * @param {module:ApiClient} [apiClient] Optional API client implementation to use, + * default to {@link module:ApiClient#instance} if unspecified. + */ + constructor(apiClient) { + this.apiClient = apiClient || ApiClient.instance; + } + + + /** + * Callback function to receive the result of the libcalSpaceBookingsGet operation. + * @callback module:api/LibCalApi~libcalSpaceBookingsGetCallback + * @param {String} error Error message, if any. + * @param {module:model/InlineResponse20039} data The data returned by the service call. + * @param {String} response The complete HTTP response. + */ + + /** + * Get all LibCal bookings + * @param {Object} opts Optional parameters + * @param {String} opts.eid Comma delimited list of LibCal space IDs. If specified, will only show bookings for those spaces. + * @param {String} opts.seatId Comma delimited list of LibCal seat IDs. If specified, will only show bookings for those seats. + * @param {String} opts.cid Comma delimited list of LibCal category IDs. If specified, will only show bookings for those categories. + * @param {String} opts.lid Comma delimited list of LibCal location IDs. If specified, will only show bookings for those locations. + * @param {String} opts._date Date in YYYY-MM-DD format. If specified, will only show bookings made on this date. Dates in the past are ignored. Defaults to today's date. + * @param {Number} opts.days Number of days into the future to retrieve bookings from, starting from the data parameter. Defaults to zero. Must be >= 0 and <= 365. + * @param {Number} opts.limit Maximum number of bookings to return. Defaults to 20. The maximum value is 500. + * @param {module:api/LibCalApi~libcalSpaceBookingsGetCallback} callback The callback function, accepting three arguments: error, data, response + * data is of type: {@link module:model/InlineResponse20039} + */ + libcalSpaceBookingsGet(opts, callback) { + opts = opts || {}; + let postBody = null; + + let pathParams = { + }; + let queryParams = { + 'eid': opts['eid'], + 'seat_id': opts['seatId'], + 'cid': opts['cid'], + 'lid': opts['lid'], + 'date': opts['_date'], + 'days': opts['days'], + 'limit': opts['limit'] + }; + let headerParams = { + }; + let formParams = { + }; + + let authNames = ['ApiToken']; + let contentTypes = []; + let accepts = ['application/json']; + let returnType = InlineResponse20039; + return this.apiClient.callApi( + '/libcal/space/bookings', 'GET', + pathParams, queryParams, headerParams, formParams, postBody, + authNames, contentTypes, accepts, returnType, null, callback + ); + } + + /** + * Callback function to receive the result of the libcalSpaceCancelPost operation. + * @callback module:api/LibCalApi~libcalSpaceCancelPostCallback + * @param {String} error Error message, if any. + * @param {module:model/InlineResponse20042} data The data returned by the service call. + * @param {String} response The complete HTTP response. + */ + + /** + * Cancel one or more LibCal bookings + * @param {String} id A comma delimited list of LibCal booking IDs to cancel + * @param {module:api/LibCalApi~libcalSpaceCancelPostCallback} callback The callback function, accepting three arguments: error, data, response + * data is of type: {@link module:model/InlineResponse20042} + */ + libcalSpaceCancelPost(id, callback) { + let postBody = null; + // verify the required parameter 'id' is set + if (id === undefined || id === null) { + throw new Error("Missing the required parameter 'id' when calling libcalSpaceCancelPost"); + } + + let pathParams = { + }; + let queryParams = { + 'id': id + }; + let headerParams = { + }; + let formParams = { + }; + + let authNames = ['OAuthSecurity', 'OAuthToken']; + let contentTypes = []; + let accepts = ['application/json']; + let returnType = InlineResponse20042; + return this.apiClient.callApi( + '/libcal/space/cancel', 'POST', + pathParams, queryParams, headerParams, formParams, postBody, + authNames, contentTypes, accepts, returnType, null, callback + ); + } + + /** + * Callback function to receive the result of the libcalSpaceCategoriesGet operation. + * @callback module:api/LibCalApi~libcalSpaceCategoriesGetCallback + * @param {String} error Error message, if any. + * @param {module:model/InlineResponse20028} data The data returned by the service call. + * @param {String} response The complete HTTP response. + */ + + /** + * Returns the categories of spaces available in the given location(s) + * @param {String} ids Comma delimited list of LibCal location IDs + * @param {module:api/LibCalApi~libcalSpaceCategoriesGetCallback} callback The callback function, accepting three arguments: error, data, response + * data is of type: {@link module:model/InlineResponse20028} + */ + libcalSpaceCategoriesGet(ids, callback) { + let postBody = null; + // verify the required parameter 'ids' is set + if (ids === undefined || ids === null) { + throw new Error("Missing the required parameter 'ids' when calling libcalSpaceCategoriesGet"); + } + + let pathParams = { + }; + let queryParams = { + 'ids': ids + }; + let headerParams = { + }; + let formParams = { + }; + + let authNames = ['ApiToken']; + let contentTypes = []; + let accepts = ['application/json']; + let returnType = InlineResponse20028; + return this.apiClient.callApi( + '/libcal/space/categories', 'GET', + pathParams, queryParams, headerParams, formParams, postBody, + authNames, contentTypes, accepts, returnType, null, callback + ); + } + + /** + * Callback function to receive the result of the libcalSpaceCategoryGet operation. + * @callback module:api/LibCalApi~libcalSpaceCategoryGetCallback + * @param {String} error Error message, if any. + * @param {module:model/InlineResponse20029} data The data returned by the service call. + * @param {String} response The complete HTTP response. + */ + + /** + * Get all spaces corresponding to the specified categories + * @param {String} ids Comma delimited list of LibCal category IDs + * @param {Object} opts Optional parameters + * @param {Number} opts.details Flag to indicate you want additional details such as terms and conditions. + * @param {String} opts.availability Either a single date or a comma delimited list of 2 dates (a start and end date). The keyword 'next' (alone) can also be used to return availability for the next date that this item is available. Setting this parameter also sets the details value to 1. Dates should be in YYYY-MM-DD format. + * @param {module:api/LibCalApi~libcalSpaceCategoryGetCallback} callback The callback function, accepting three arguments: error, data, response + * data is of type: {@link module:model/InlineResponse20029} + */ + libcalSpaceCategoryGet(ids, opts, callback) { + opts = opts || {}; + let postBody = null; + // verify the required parameter 'ids' is set + if (ids === undefined || ids === null) { + throw new Error("Missing the required parameter 'ids' when calling libcalSpaceCategoryGet"); + } + + let pathParams = { + }; + let queryParams = { + 'ids': ids, + 'details': opts['details'], + 'availability': opts['availability'] + }; + let headerParams = { + }; + let formParams = { + }; + + let authNames = ['ApiToken']; + let contentTypes = []; + let accepts = ['application/json']; + let returnType = InlineResponse20029; + return this.apiClient.callApi( + '/libcal/space/category', 'GET', + pathParams, queryParams, headerParams, formParams, postBody, + authNames, contentTypes, accepts, returnType, null, callback + ); + } + + /** + * Callback function to receive the result of the libcalSpaceFormGet operation. + * @callback module:api/LibCalApi~libcalSpaceFormGetCallback + * @param {String} error Error message, if any. + * @param {module:model/InlineResponse20030} data The data returned by the service call. + * @param {String} response The complete HTTP response. + */ + + /** + * Get all forms (including fields) corresponding to the given LibCal form ID(s) + * @param {String} ids Comma delimited list of LibCal form IDs + * @param {module:api/LibCalApi~libcalSpaceFormGetCallback} callback The callback function, accepting three arguments: error, data, response + * data is of type: {@link module:model/InlineResponse20030} + */ + libcalSpaceFormGet(ids, callback) { + let postBody = null; + // verify the required parameter 'ids' is set + if (ids === undefined || ids === null) { + throw new Error("Missing the required parameter 'ids' when calling libcalSpaceFormGet"); + } + + let pathParams = { + }; + let queryParams = { + 'ids': ids + }; + let headerParams = { + }; + let formParams = { + }; + + let authNames = ['ApiToken']; + let contentTypes = []; + let accepts = ['application/json']; + let returnType = InlineResponse20030; + return this.apiClient.callApi( + '/libcal/space/form', 'GET', + pathParams, queryParams, headerParams, formParams, postBody, + authNames, contentTypes, accepts, returnType, null, callback + ); + } + + /** + * Callback function to receive the result of the libcalSpaceItemGet operation. + * @callback module:api/LibCalApi~libcalSpaceItemGetCallback + * @param {String} error Error message, if any. + * @param {module:model/InlineResponse20032} data The data returned by the service call. + * @param {String} response The complete HTTP response. + */ + + /** + * Get the spaces corresponding to the given LibCal space ID(s) + * @param {String} ids Comma delimited list of LibCal space IDs + * @param {Object} opts Optional parameters + * @param {String} opts.availability Either a single date or a comma delimited list of 2 dates (a start and end date). The keyword 'next' (alone) can also be used to return availability for the next date that this item is available. Setting this parameter also sets the details value to 1. Dates should be in YYYY-MM-DD format. + * @param {module:api/LibCalApi~libcalSpaceItemGetCallback} callback The callback function, accepting three arguments: error, data, response + * data is of type: {@link module:model/InlineResponse20032} + */ + libcalSpaceItemGet(ids, opts, callback) { + opts = opts || {}; + let postBody = null; + // verify the required parameter 'ids' is set + if (ids === undefined || ids === null) { + throw new Error("Missing the required parameter 'ids' when calling libcalSpaceItemGet"); + } + + let pathParams = { + }; + let queryParams = { + 'ids': ids, + 'availability': opts['availability'] + }; + let headerParams = { + }; + let formParams = { + }; + + let authNames = ['ApiToken']; + let contentTypes = []; + let accepts = ['application/json']; + let returnType = InlineResponse20032; + return this.apiClient.callApi( + '/libcal/space/item', 'GET', + pathParams, queryParams, headerParams, formParams, postBody, + authNames, contentTypes, accepts, returnType, null, callback + ); + } + + /** + * Callback function to receive the result of the libcalSpaceLocationsGet operation. + * @callback module:api/LibCalApi~libcalSpaceLocationsGetCallback + * @param {String} error Error message, if any. + * @param {module:model/InlineResponse20027} data The data returned by the service call. + * @param {String} response The complete HTTP response. + */ + + /** + * Gets all LibCal locations + * @param {Object} opts Optional parameters + * @param {Number} opts.details Flag to indicate you want additional details such as terms and conditions. + * @param {module:api/LibCalApi~libcalSpaceLocationsGetCallback} callback The callback function, accepting three arguments: error, data, response + * data is of type: {@link module:model/InlineResponse20027} + */ + libcalSpaceLocationsGet(opts, callback) { + opts = opts || {}; + let postBody = null; + + let pathParams = { + }; + let queryParams = { + 'details': opts['details'] + }; + let headerParams = { + }; + let formParams = { + }; + + let authNames = ['ApiToken']; + let contentTypes = []; + let accepts = ['application/json']; + let returnType = InlineResponse20027; + return this.apiClient.callApi( + '/libcal/space/locations', 'GET', + pathParams, queryParams, headerParams, formParams, postBody, + authNames, contentTypes, accepts, returnType, null, callback + ); + } + + /** + * Callback function to receive the result of the libcalSpaceNicknameGet operation. + * @callback module:api/LibCalApi~libcalSpaceNicknameGetCallback + * @param {String} error Error message, if any. + * @param {module:model/InlineResponse20033} data The data returned by the service call. + * @param {String} response The complete HTTP response. + */ + + /** + * Get the nicknames asssigned to certain LibCal bookings + * @param {String} ids Comma delimited list of LibCal category IDs + * @param {Object} opts Optional parameters + * @param {String} opts.availability Either a single date or a comma delimited list of 2 dates (a start and end date). The keyword 'next' (alone) can also be used to return availability for the next date that this item is available. Setting this parameter also sets the details value to 1. Dates should be in YYYY-MM-DD format. + * @param {module:api/LibCalApi~libcalSpaceNicknameGetCallback} callback The callback function, accepting three arguments: error, data, response + * data is of type: {@link module:model/InlineResponse20033} + */ + libcalSpaceNicknameGet(ids, opts, callback) { + opts = opts || {}; + let postBody = null; + // verify the required parameter 'ids' is set + if (ids === undefined || ids === null) { + throw new Error("Missing the required parameter 'ids' when calling libcalSpaceNicknameGet"); + } + + let pathParams = { + }; + let queryParams = { + 'ids': ids, + 'availability': opts['availability'] + }; + let headerParams = { + }; + let formParams = { + }; + + let authNames = ['ApiToken']; + let contentTypes = []; + let accepts = ['application/json']; + let returnType = InlineResponse20033; + return this.apiClient.callApi( + '/libcal/space/nickname', 'GET', + pathParams, queryParams, headerParams, formParams, postBody, + authNames, contentTypes, accepts, returnType, null, callback + ); + } + + /** + * Callback function to receive the result of the libcalSpacePersonalBookingsGet operation. + * @callback module:api/LibCalApi~libcalSpacePersonalBookingsGetCallback + * @param {String} error Error message, if any. + * @param {module:model/InlineResponse20040} data The data returned by the service call. + * @param {String} response The complete HTTP response. + */ + + /** + * Get all LibCal bookings + * @param {String} clientSecret Client secret of the authenticating app. + * @param {Object} opts Optional parameters + * @param {String} opts.eid Comma delimited list of LibCal space IDs. If specified, will only show bookings for those spaces. + * @param {String} opts.seatId Comma delimited list of LibCal seat IDs. If specified, will only show bookings for those seats. + * @param {String} opts.cid Comma delimited list of LibCal category IDs. If specified, will only show bookings for those categories. + * @param {String} opts.lid Comma delimited list of LibCal location IDs. If specified, will only show bookings for those locations. + * @param {String} opts.email If specified, will only show bookings made with this email address + * @param {String} opts._date Date in YYYY-MM-DD format. If specified, will only show bookings made on this date. Dates in the past are ignored. Defaults to today's date. + * @param {Number} opts.days Number of days into the future to retrieve bookings from, starting from the data parameter. Defaults to zero. Must be >= 0 and <= 365. + * @param {Number} opts.limit Maximum number of bookings to return. Defaults to 20. The maximum value is 500. + * @param {Boolean} opts.formAnswers Whether or not form answers should be returned. Defaults to false. + * @param {module:api/LibCalApi~libcalSpacePersonalBookingsGetCallback} callback The callback function, accepting three arguments: error, data, response + * data is of type: {@link module:model/InlineResponse20040} + */ + libcalSpacePersonalBookingsGet(clientSecret, opts, callback) { + opts = opts || {}; + let postBody = null; + // verify the required parameter 'clientSecret' is set + if (clientSecret === undefined || clientSecret === null) { + throw new Error("Missing the required parameter 'clientSecret' when calling libcalSpacePersonalBookingsGet"); + } + + let pathParams = { + }; + let queryParams = { + 'client_secret': clientSecret, + 'eid': opts['eid'], + 'seat_id': opts['seatId'], + 'cid': opts['cid'], + 'lid': opts['lid'], + 'email': opts['email'], + 'date': opts['_date'], + 'days': opts['days'], + 'limit': opts['limit'], + 'form_answers': opts['formAnswers'] + }; + let headerParams = { + }; + let formParams = { + }; + + let authNames = ['OAuthSecurity', 'OAuthToken']; + let contentTypes = []; + let accepts = ['application/json']; + let returnType = InlineResponse20040; + return this.apiClient.callApi( + '/libcal/space/personal_bookings', 'GET', + pathParams, queryParams, headerParams, formParams, postBody, + authNames, contentTypes, accepts, returnType, null, callback + ); + } + + /** + * Callback function to receive the result of the libcalSpaceQuestionGet operation. + * @callback module:api/LibCalApi~libcalSpaceQuestionGetCallback + * @param {String} error Error message, if any. + * @param {module:model/InlineResponse20031} data The data returned by the service call. + * @param {String} response The complete HTTP response. + */ + + /** + * Get the questions corresponding to the given LibCal field/question ID(s) + * @param {String} ids Comma delimited list of LibCal field/question IDs + * @param {module:api/LibCalApi~libcalSpaceQuestionGetCallback} callback The callback function, accepting three arguments: error, data, response + * data is of type: {@link module:model/InlineResponse20031} + */ + libcalSpaceQuestionGet(ids, callback) { + let postBody = null; + // verify the required parameter 'ids' is set + if (ids === undefined || ids === null) { + throw new Error("Missing the required parameter 'ids' when calling libcalSpaceQuestionGet"); + } + + let pathParams = { + }; + let queryParams = { + 'ids': ids + }; + let headerParams = { + }; + let formParams = { + }; + + let authNames = ['ApiToken']; + let contentTypes = []; + let accepts = ['application/json']; + let returnType = InlineResponse20031; + return this.apiClient.callApi( + '/libcal/space/question', 'GET', + pathParams, queryParams, headerParams, formParams, postBody, + authNames, contentTypes, accepts, returnType, null, callback + ); + } + + /** + * Callback function to receive the result of the libcalSpaceReservePost operation. + * @callback module:api/LibCalApi~libcalSpaceReservePostCallback + * @param {String} error Error message, if any. + * @param {module:model/InlineResponse20041} data The data returned by the service call. + * @param {String} response The complete HTTP response. + */ + + /** + * Reserve one or more LibCal spaces/seats + * @param {module:model/LibcalReserveRequest} libcalReserveRequest + * @param {module:api/LibCalApi~libcalSpaceReservePostCallback} callback The callback function, accepting three arguments: error, data, response + * data is of type: {@link module:model/InlineResponse20041} + */ + libcalSpaceReservePost(libcalReserveRequest, callback) { + let postBody = libcalReserveRequest; + // verify the required parameter 'libcalReserveRequest' is set + if (libcalReserveRequest === undefined || libcalReserveRequest === null) { + throw new Error("Missing the required parameter 'libcalReserveRequest' when calling libcalSpaceReservePost"); + } + + let pathParams = { + }; + let queryParams = { + }; + let headerParams = { + }; + let formParams = { + }; + + let authNames = ['OAuthSecurity', 'OAuthToken']; + let contentTypes = ['application/json']; + let accepts = ['application/json']; + let returnType = InlineResponse20041; + return this.apiClient.callApi( + '/libcal/space/reserve', 'POST', + pathParams, queryParams, headerParams, formParams, postBody, + authNames, contentTypes, accepts, returnType, null, callback + ); + } + + /** + * Callback function to receive the result of the libcalSpaceSeatGet operation. + * @callback module:api/LibCalApi~libcalSpaceSeatGetCallback + * @param {String} error Error message, if any. + * @param {module:model/InlineResponse20036} data The data returned by the service call. + * @param {String} response The complete HTTP response. + */ + + /** + * Get LibCal seat by ID + * @param {String} ids Comma delimited list of LibCal category IDs + * @param {Object} opts Optional parameters + * @param {String} opts.availability Either a single date or a comma delimited list of 2 dates (a start and end date). The keyword 'next' (alone) can also be used to return availability for the next date that this item is available. Setting this parameter also sets the details value to 1. Dates should be in YYYY-MM-DD format. + * @param {module:api/LibCalApi~libcalSpaceSeatGetCallback} callback The callback function, accepting three arguments: error, data, response + * data is of type: {@link module:model/InlineResponse20036} + */ + libcalSpaceSeatGet(ids, opts, callback) { + opts = opts || {}; + let postBody = null; + // verify the required parameter 'ids' is set + if (ids === undefined || ids === null) { + throw new Error("Missing the required parameter 'ids' when calling libcalSpaceSeatGet"); + } + + let pathParams = { + }; + let queryParams = { + 'ids': ids, + 'availability': opts['availability'] + }; + let headerParams = { + }; + let formParams = { + }; + + let authNames = ['ApiToken']; + let contentTypes = []; + let accepts = ['application/json']; + let returnType = InlineResponse20036; + return this.apiClient.callApi( + '/libcal/space/seat', 'GET', + pathParams, queryParams, headerParams, formParams, postBody, + authNames, contentTypes, accepts, returnType, null, callback + ); + } + + /** + * Callback function to receive the result of the libcalSpaceSeatsGet operation. + * @callback module:api/LibCalApi~libcalSpaceSeatsGetCallback + * @param {String} error Error message, if any. + * @param {module:model/InlineResponse20035} data The data returned by the service call. + * @param {String} response The complete HTTP response. + */ + + /** + * Get all LibCal seats in a given location + * @param {String} ids A single LibCal location ID + * @param {Object} opts Optional parameters + * @param {String} opts.spaceId If specified, only return data for this space + * @param {String} opts.categoryId If specified, will only return data for that category + * @param {String} opts.seatId Show only the seat with this ID. If this is specified, spaceId, categoryId, and zoneId will be ignored. + * @param {Boolean} opts.accessibleOnly Return only acessible seats (i.e. seats with height-adjustable furniture). + * @param {String} opts.availability Either a single date or a comma delimited list of 2 dates (a start and end date). The keyword 'next' (alone) can also be used to return availability for the next date that this item is available. Setting this parameter also sets the details value to 1. Dates should be in YYYY-MM-DD format. + * @param {Number} opts.pageIndex For pagination purposes, this specifies the page to be retrieved. Starts at 0 for the first page. + * @param {Number} opts.pageSize For pagination purposes, this specifies the number of results per page. Must be >= 1 and <= 100. The default is 20. + * @param {module:api/LibCalApi~libcalSpaceSeatsGetCallback} callback The callback function, accepting three arguments: error, data, response + * data is of type: {@link module:model/InlineResponse20035} + */ + libcalSpaceSeatsGet(ids, opts, callback) { + opts = opts || {}; + let postBody = null; + // verify the required parameter 'ids' is set + if (ids === undefined || ids === null) { + throw new Error("Missing the required parameter 'ids' when calling libcalSpaceSeatsGet"); + } + + let pathParams = { + }; + let queryParams = { + 'ids': ids, + 'space_id': opts['spaceId'], + 'category_id': opts['categoryId'], + 'seat_id': opts['seatId'], + 'accessible_only': opts['accessibleOnly'], + 'availability': opts['availability'], + 'page_index': opts['pageIndex'], + 'page_size': opts['pageSize'] + }; + let headerParams = { + }; + let formParams = { + }; + + let authNames = ['ApiToken']; + let contentTypes = []; + let accepts = ['application/json']; + let returnType = InlineResponse20035; + return this.apiClient.callApi( + '/libcal/space/seats', 'GET', + pathParams, queryParams, headerParams, formParams, postBody, + authNames, contentTypes, accepts, returnType, null, callback + ); + } + + /** + * Callback function to receive the result of the libcalSpaceUtilizationGet operation. + * @callback module:api/LibCalApi~libcalSpaceUtilizationGetCallback + * @param {String} error Error message, if any. + * @param {module:model/InlineResponse20034} data The data returned by the service call. + * @param {String} response The complete HTTP response. + */ + + /** + * Get utilisation stats for a particular location + * Optionally filter by categoryId and zoneId + * @param {String} ids A single LibCal location ID + * @param {Object} opts Optional parameters + * @param {String} opts.categoryId If specified, will only return data for that category + * @param {String} opts.zoneId If specified, will only return data for that zone + * @param {module:api/LibCalApi~libcalSpaceUtilizationGetCallback} callback The callback function, accepting three arguments: error, data, response + * data is of type: {@link module:model/InlineResponse20034} + */ + libcalSpaceUtilizationGet(ids, opts, callback) { + opts = opts || {}; + let postBody = null; + // verify the required parameter 'ids' is set + if (ids === undefined || ids === null) { + throw new Error("Missing the required parameter 'ids' when calling libcalSpaceUtilizationGet"); + } + + let pathParams = { + }; + let queryParams = { + 'ids': ids, + 'category_id': opts['categoryId'], + 'zone_id': opts['zoneId'] + }; + let headerParams = { + }; + let formParams = { + }; + + let authNames = ['ApiToken']; + let contentTypes = []; + let accepts = ['application/json']; + let returnType = InlineResponse20034; + return this.apiClient.callApi( + '/libcal/space/utilization', 'GET', + pathParams, queryParams, headerParams, formParams, postBody, + authNames, contentTypes, accepts, returnType, null, callback + ); + } + + /** + * Callback function to receive the result of the libcalSpaceZoneGet operation. + * @callback module:api/LibCalApi~libcalSpaceZoneGetCallback + * @param {String} error Error message, if any. + * @param {module:model/InlineResponse20038} data The data returned by the service call. + * @param {String} response The complete HTTP response. + */ + + /** + * Get LibCal zone by ID + * @param {Object} opts Optional parameters + * @param {String} opts.zoneId If specified, will only return data for that zone + * @param {module:api/LibCalApi~libcalSpaceZoneGetCallback} callback The callback function, accepting three arguments: error, data, response + * data is of type: {@link module:model/InlineResponse20038} + */ + libcalSpaceZoneGet(opts, callback) { + opts = opts || {}; + let postBody = null; + + let pathParams = { + }; + let queryParams = { + 'zone_id': opts['zoneId'] + }; + let headerParams = { + }; + let formParams = { + }; + + let authNames = ['ApiToken']; + let contentTypes = []; + let accepts = ['application/json']; + let returnType = InlineResponse20038; + return this.apiClient.callApi( + '/libcal/space/zone', 'GET', + pathParams, queryParams, headerParams, formParams, postBody, + authNames, contentTypes, accepts, returnType, null, callback + ); + } + + /** + * Callback function to receive the result of the libcalSpaceZonesGet operation. + * @callback module:api/LibCalApi~libcalSpaceZonesGetCallback + * @param {String} error Error message, if any. + * @param {module:model/InlineResponse20037} data The data returned by the service call. + * @param {String} response The complete HTTP response. + */ + + /** + * Get LibCal zones by location + * @param {String} ids A single LibCal location ID + * @param {module:api/LibCalApi~libcalSpaceZonesGetCallback} callback The callback function, accepting three arguments: error, data, response + * data is of type: {@link module:model/InlineResponse20037} + */ + libcalSpaceZonesGet(ids, callback) { + let postBody = null; + // verify the required parameter 'ids' is set + if (ids === undefined || ids === null) { + throw new Error("Missing the required parameter 'ids' when calling libcalSpaceZonesGet"); + } + + let pathParams = { + }; + let queryParams = { + 'ids': ids + }; + let headerParams = { + }; + let formParams = { + }; + + let authNames = ['ApiToken']; + let contentTypes = []; + let accepts = ['application/json']; + let returnType = InlineResponse20037; + return this.apiClient.callApi( + '/libcal/space/zones', 'GET', + pathParams, queryParams, headerParams, formParams, postBody, + authNames, contentTypes, accepts, returnType, null, callback + ); + } + + +} diff --git a/src/api/OAuthApi.js b/src/api/OAuthApi.js index 523f095d..16bdb291 100644 --- a/src/api/OAuthApi.js +++ b/src/api/OAuthApi.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -21,7 +21,7 @@ import UserData from '../model/UserData'; /** * OAuth service. * @module api/OAuthApi -* @version 1.0.3 +* @version 1.4.2 */ export default class OAuthApi { diff --git a/src/api/ResourcesApi.js b/src/api/ResourcesApi.js index 961cf92d..65a6d5d5 100644 --- a/src/api/ResourcesApi.js +++ b/src/api/ResourcesApi.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -19,7 +19,7 @@ import InlineResponse20011 from '../model/InlineResponse20011'; /** * Resources service. * @module api/ResourcesApi -* @version 1.0.3 +* @version 1.4.2 */ export default class ResourcesApi { diff --git a/src/api/RoomBookingsApi.js b/src/api/RoomBookingsApi.js index 6d832e19..580f0d9b 100644 --- a/src/api/RoomBookingsApi.js +++ b/src/api/RoomBookingsApi.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -22,7 +22,7 @@ import InlineResponse2009 from '../model/InlineResponse2009'; /** * RoomBookings service. * @module api/RoomBookingsApi -* @version 1.0.3 +* @version 1.4.2 */ export default class RoomBookingsApi { diff --git a/src/api/SearchApi.js b/src/api/SearchApi.js index 99c4b7b7..a64167de 100644 --- a/src/api/SearchApi.js +++ b/src/api/SearchApi.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -19,7 +19,7 @@ import InlineResponse20010 from '../model/InlineResponse20010'; /** * Search service. * @module api/SearchApi -* @version 1.0.3 +* @version 1.4.2 */ export default class SearchApi { diff --git a/src/api/TimetableApi.js b/src/api/TimetableApi.js index da02af55..14cc7aca 100644 --- a/src/api/TimetableApi.js +++ b/src/api/TimetableApi.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -22,7 +22,7 @@ import InlineResponse2003 from '../model/InlineResponse2003'; /** * Timetable service. * @module api/TimetableApi -* @version 1.0.3 +* @version 1.4.2 */ export default class TimetableApi { diff --git a/src/api/WorkspacesApi.js b/src/api/WorkspacesApi.js index 7c04185a..e3b4b63d 100644 --- a/src/api/WorkspacesApi.js +++ b/src/api/WorkspacesApi.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -28,7 +28,7 @@ import Svg from '../model/Svg'; /** * Workspaces service. * @module api/WorkspacesApi -* @version 1.0.3 +* @version 1.4.2 */ export default class WorkspacesApi { diff --git a/src/index.js b/src/index.js index 0176d09d..1fff9334 100644 --- a/src/index.js +++ b/src/index.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -53,8 +53,25 @@ import InlineResponse20024Data from './model/InlineResponse20024Data'; import InlineResponse20025 from './model/InlineResponse20025'; import InlineResponse20026 from './model/InlineResponse20026'; import InlineResponse20026Data from './model/InlineResponse20026Data'; +import InlineResponse20027 from './model/InlineResponse20027'; +import InlineResponse20028 from './model/InlineResponse20028'; +import InlineResponse20029 from './model/InlineResponse20029'; +import InlineResponse20029Categories from './model/InlineResponse20029Categories'; import InlineResponse2003 from './model/InlineResponse2003'; +import InlineResponse20030 from './model/InlineResponse20030'; +import InlineResponse20031 from './model/InlineResponse20031'; +import InlineResponse20032 from './model/InlineResponse20032'; +import InlineResponse20033 from './model/InlineResponse20033'; +import InlineResponse20034 from './model/InlineResponse20034'; +import InlineResponse20035 from './model/InlineResponse20035'; +import InlineResponse20036 from './model/InlineResponse20036'; +import InlineResponse20037 from './model/InlineResponse20037'; +import InlineResponse20038 from './model/InlineResponse20038'; +import InlineResponse20039 from './model/InlineResponse20039'; import InlineResponse2004 from './model/InlineResponse2004'; +import InlineResponse20040 from './model/InlineResponse20040'; +import InlineResponse20041 from './model/InlineResponse20041'; +import InlineResponse20042 from './model/InlineResponse20042'; import InlineResponse2005 from './model/InlineResponse2005'; import InlineResponse2006 from './model/InlineResponse2006'; import InlineResponse2007 from './model/InlineResponse2007'; @@ -62,6 +79,21 @@ import InlineResponse2008 from './model/InlineResponse2008'; import InlineResponse2009 from './model/InlineResponse2009'; import Instance from './model/Instance'; import Lecturer from './model/Lecturer'; +import LibcalBooking from './model/LibcalBooking'; +import LibcalCategory from './model/LibcalCategory'; +import LibcalForm from './model/LibcalForm'; +import LibcalFormField from './model/LibcalFormField'; +import LibcalLocation from './model/LibcalLocation'; +import LibcalLocationBase from './model/LibcalLocationBase'; +import LibcalPersonalSeatBooking from './model/LibcalPersonalSeatBooking'; +import LibcalReserveRequest from './model/LibcalReserveRequest'; +import LibcalReserveRequestBooking from './model/LibcalReserveRequestBooking'; +import LibcalSeat from './model/LibcalSeat'; +import LibcalSeatBooking from './model/LibcalSeatBooking'; +import LibcalSpaceBase from './model/LibcalSpaceBase'; +import LibcalUtilisationSeatSummary from './model/LibcalUtilisationSeatSummary'; +import LibcalUtilisationSpaceSummary from './model/LibcalUtilisationSpaceSummary'; +import LibcalZone from './model/LibcalZone'; import Location from './model/Location'; import LocationCoordinates from './model/LocationCoordinates'; import Map from './model/Map'; @@ -89,6 +121,7 @@ import TeachingPeriods from './model/TeachingPeriods'; import Timetable from './model/Timetable'; import UserData from './model/UserData'; import AnalyticsApi from './api/AnalyticsApi'; +import LibCalApi from './api/LibCalApi'; import OAuthApi from './api/OAuthApi'; import ResourcesApi from './api/ResourcesApi'; import RoomBookingsApi from './api/RoomBookingsApi'; @@ -126,7 +159,7 @@ import WorkspacesApi from './api/WorkspacesApi'; * *

* @module index -* @version 1.0.3 +* @version 1.4.2 */ export { /** @@ -375,18 +408,120 @@ export { */ InlineResponse20026Data, + /** + * The InlineResponse20027 model constructor. + * @property {module:model/InlineResponse20027} + */ + InlineResponse20027, + + /** + * The InlineResponse20028 model constructor. + * @property {module:model/InlineResponse20028} + */ + InlineResponse20028, + + /** + * The InlineResponse20029 model constructor. + * @property {module:model/InlineResponse20029} + */ + InlineResponse20029, + + /** + * The InlineResponse20029Categories model constructor. + * @property {module:model/InlineResponse20029Categories} + */ + InlineResponse20029Categories, + /** * The InlineResponse2003 model constructor. * @property {module:model/InlineResponse2003} */ InlineResponse2003, + /** + * The InlineResponse20030 model constructor. + * @property {module:model/InlineResponse20030} + */ + InlineResponse20030, + + /** + * The InlineResponse20031 model constructor. + * @property {module:model/InlineResponse20031} + */ + InlineResponse20031, + + /** + * The InlineResponse20032 model constructor. + * @property {module:model/InlineResponse20032} + */ + InlineResponse20032, + + /** + * The InlineResponse20033 model constructor. + * @property {module:model/InlineResponse20033} + */ + InlineResponse20033, + + /** + * The InlineResponse20034 model constructor. + * @property {module:model/InlineResponse20034} + */ + InlineResponse20034, + + /** + * The InlineResponse20035 model constructor. + * @property {module:model/InlineResponse20035} + */ + InlineResponse20035, + + /** + * The InlineResponse20036 model constructor. + * @property {module:model/InlineResponse20036} + */ + InlineResponse20036, + + /** + * The InlineResponse20037 model constructor. + * @property {module:model/InlineResponse20037} + */ + InlineResponse20037, + + /** + * The InlineResponse20038 model constructor. + * @property {module:model/InlineResponse20038} + */ + InlineResponse20038, + + /** + * The InlineResponse20039 model constructor. + * @property {module:model/InlineResponse20039} + */ + InlineResponse20039, + /** * The InlineResponse2004 model constructor. * @property {module:model/InlineResponse2004} */ InlineResponse2004, + /** + * The InlineResponse20040 model constructor. + * @property {module:model/InlineResponse20040} + */ + InlineResponse20040, + + /** + * The InlineResponse20041 model constructor. + * @property {module:model/InlineResponse20041} + */ + InlineResponse20041, + + /** + * The InlineResponse20042 model constructor. + * @property {module:model/InlineResponse20042} + */ + InlineResponse20042, + /** * The InlineResponse2005 model constructor. * @property {module:model/InlineResponse2005} @@ -429,6 +564,96 @@ export { */ Lecturer, + /** + * The LibcalBooking model constructor. + * @property {module:model/LibcalBooking} + */ + LibcalBooking, + + /** + * The LibcalCategory model constructor. + * @property {module:model/LibcalCategory} + */ + LibcalCategory, + + /** + * The LibcalForm model constructor. + * @property {module:model/LibcalForm} + */ + LibcalForm, + + /** + * The LibcalFormField model constructor. + * @property {module:model/LibcalFormField} + */ + LibcalFormField, + + /** + * The LibcalLocation model constructor. + * @property {module:model/LibcalLocation} + */ + LibcalLocation, + + /** + * The LibcalLocationBase model constructor. + * @property {module:model/LibcalLocationBase} + */ + LibcalLocationBase, + + /** + * The LibcalPersonalSeatBooking model constructor. + * @property {module:model/LibcalPersonalSeatBooking} + */ + LibcalPersonalSeatBooking, + + /** + * The LibcalReserveRequest model constructor. + * @property {module:model/LibcalReserveRequest} + */ + LibcalReserveRequest, + + /** + * The LibcalReserveRequestBooking model constructor. + * @property {module:model/LibcalReserveRequestBooking} + */ + LibcalReserveRequestBooking, + + /** + * The LibcalSeat model constructor. + * @property {module:model/LibcalSeat} + */ + LibcalSeat, + + /** + * The LibcalSeatBooking model constructor. + * @property {module:model/LibcalSeatBooking} + */ + LibcalSeatBooking, + + /** + * The LibcalSpaceBase model constructor. + * @property {module:model/LibcalSpaceBase} + */ + LibcalSpaceBase, + + /** + * The LibcalUtilisationSeatSummary model constructor. + * @property {module:model/LibcalUtilisationSeatSummary} + */ + LibcalUtilisationSeatSummary, + + /** + * The LibcalUtilisationSpaceSummary model constructor. + * @property {module:model/LibcalUtilisationSpaceSummary} + */ + LibcalUtilisationSpaceSummary, + + /** + * The LibcalZone model constructor. + * @property {module:model/LibcalZone} + */ + LibcalZone, + /** * The Location model constructor. * @property {module:model/Location} @@ -591,6 +816,12 @@ export { */ AnalyticsApi, + /** + * The LibCalApi service constructor. + * @property {module:api/LibCalApi} + */ + LibCalApi, + /** * The OAuthApi service constructor. * @property {module:api/OAuthApi} diff --git a/src/model/Average.js b/src/model/Average.js index 10ec687c..39acb3ac 100644 --- a/src/model/Average.js +++ b/src/model/Average.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -16,7 +16,7 @@ import ApiClient from '../ApiClient'; /** * The Average model module. * @module model/Average - * @version 1.0.3 + * @version 1.4.2 */ class Average { /** diff --git a/src/model/AverageWithNameAndId.js b/src/model/AverageWithNameAndId.js index 4e354d13..ba4502b5 100644 --- a/src/model/AverageWithNameAndId.js +++ b/src/model/AverageWithNameAndId.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -16,7 +16,7 @@ import ApiClient from '../ApiClient'; /** * The AverageWithNameAndId model module. * @module model/AverageWithNameAndId - * @version 1.0.3 + * @version 1.4.2 */ class AverageWithNameAndId { /** diff --git a/src/model/Booking.js b/src/model/Booking.js index d077dd9a..f9e44d0e 100644 --- a/src/model/Booking.js +++ b/src/model/Booking.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -16,7 +16,7 @@ import ApiClient from '../ApiClient'; /** * The Booking model module. * @module model/Booking - * @version 1.0.3 + * @version 1.4.2 */ class Booking { /** diff --git a/src/model/Course.js b/src/model/Course.js index b6ad9939..beb6676c 100644 --- a/src/model/Course.js +++ b/src/model/Course.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -16,7 +16,7 @@ import ApiClient from '../ApiClient'; /** * The Course model module. * @module model/Course - * @version 1.0.3 + * @version 1.4.2 */ class Course { /** diff --git a/src/model/Delivery.js b/src/model/Delivery.js index eee2efb9..5322561e 100644 --- a/src/model/Delivery.js +++ b/src/model/Delivery.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -16,7 +16,7 @@ import ApiClient from '../ApiClient'; /** * The Delivery model module. * @module model/Delivery - * @version 1.0.3 + * @version 1.4.2 */ class Delivery { /** diff --git a/src/model/Department.js b/src/model/Department.js index 70d2dc66..b0952c32 100644 --- a/src/model/Department.js +++ b/src/model/Department.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -16,7 +16,7 @@ import ApiClient from '../ApiClient'; /** * The Department model module. * @module model/Department - * @version 1.0.3 + * @version 1.4.2 */ class Department { /** diff --git a/src/model/DesktopData.js b/src/model/DesktopData.js index 4b1d847d..da4796aa 100644 --- a/src/model/DesktopData.js +++ b/src/model/DesktopData.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -17,7 +17,7 @@ import DesktopDataLocation from './DesktopDataLocation'; /** * The DesktopData model module. * @module model/DesktopData - * @version 1.0.3 + * @version 1.4.2 */ class DesktopData { /** diff --git a/src/model/DesktopDataLocation.js b/src/model/DesktopDataLocation.js index e34504d6..3fe520f5 100644 --- a/src/model/DesktopDataLocation.js +++ b/src/model/DesktopDataLocation.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -16,7 +16,7 @@ import ApiClient from '../ApiClient'; /** * The DesktopDataLocation model module. * @module model/DesktopDataLocation - * @version 1.0.3 + * @version 1.4.2 */ class DesktopDataLocation { /** diff --git a/src/model/Equipment.js b/src/model/Equipment.js index d29eea9a..cb0dc26d 100644 --- a/src/model/Equipment.js +++ b/src/model/Equipment.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -16,7 +16,7 @@ import ApiClient from '../ApiClient'; /** * The Equipment model module. * @module model/Equipment - * @version 1.0.3 + * @version 1.4.2 */ class Equipment { /** diff --git a/src/model/Error.js b/src/model/Error.js index 109682e2..2f41ef46 100644 --- a/src/model/Error.js +++ b/src/model/Error.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -16,7 +16,7 @@ import ApiClient from '../ApiClient'; /** * The Error model module. * @module model/Error - * @version 1.0.3 + * @version 1.4.2 */ class Error { /** diff --git a/src/model/Event.js b/src/model/Event.js index 0fbba2a4..1a9f2459 100644 --- a/src/model/Event.js +++ b/src/model/Event.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -18,7 +18,7 @@ import Module from './Module'; /** * The Event model module. * @module model/Event - * @version 1.0.3 + * @version 1.4.2 */ class Event { /** diff --git a/src/model/HistoricalSensor.js b/src/model/HistoricalSensor.js index 0e952c69..9d5c4186 100644 --- a/src/model/HistoricalSensor.js +++ b/src/model/HistoricalSensor.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -16,7 +16,7 @@ import ApiClient from '../ApiClient'; /** * The HistoricalSensor model module. * @module model/HistoricalSensor - * @version 1.0.3 + * @version 1.4.2 */ class HistoricalSensor { /** diff --git a/src/model/HistoricalSurvey.js b/src/model/HistoricalSurvey.js index 752e2be7..e02dce78 100644 --- a/src/model/HistoricalSurvey.js +++ b/src/model/HistoricalSurvey.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -16,7 +16,7 @@ import ApiClient from '../ApiClient'; /** * The HistoricalSurvey model module. * @module model/HistoricalSurvey - * @version 1.0.3 + * @version 1.4.2 */ class HistoricalSurvey { /** diff --git a/src/model/HistoricalSurveyData.js b/src/model/HistoricalSurveyData.js index c1933e2e..d2f4f408 100644 --- a/src/model/HistoricalSurveyData.js +++ b/src/model/HistoricalSurveyData.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -16,7 +16,7 @@ import ApiClient from '../ApiClient'; /** * The HistoricalSurveyData model module. * @module model/HistoricalSurveyData - * @version 1.0.3 + * @version 1.4.2 */ class HistoricalSurveyData { /** diff --git a/src/model/InlineResponse200.js b/src/model/InlineResponse200.js index fb224d75..62a4b1d3 100644 --- a/src/model/InlineResponse200.js +++ b/src/model/InlineResponse200.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -17,7 +17,7 @@ import Timetable from './Timetable'; /** * The InlineResponse200 model module. * @module model/InlineResponse200 - * @version 1.0.3 + * @version 1.4.2 */ class InlineResponse200 { /** diff --git a/src/model/InlineResponse2001.js b/src/model/InlineResponse2001.js index 650636d9..c43d4ab2 100644 --- a/src/model/InlineResponse2001.js +++ b/src/model/InlineResponse2001.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -17,7 +17,7 @@ import Department from './Department'; /** * The InlineResponse2001 model module. * @module model/InlineResponse2001 - * @version 1.0.3 + * @version 1.4.2 */ class InlineResponse2001 { /** diff --git a/src/model/InlineResponse20010.js b/src/model/InlineResponse20010.js index 1ab9ae0e..bdfcaaaf 100644 --- a/src/model/InlineResponse20010.js +++ b/src/model/InlineResponse20010.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -17,7 +17,7 @@ import Person from './Person'; /** * The InlineResponse20010 model module. * @module model/InlineResponse20010 - * @version 1.0.3 + * @version 1.4.2 */ class InlineResponse20010 { /** diff --git a/src/model/InlineResponse20011.js b/src/model/InlineResponse20011.js index 70a77ede..ae21a352 100644 --- a/src/model/InlineResponse20011.js +++ b/src/model/InlineResponse20011.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -17,7 +17,7 @@ import DesktopData from './DesktopData'; /** * The InlineResponse20011 model module. * @module model/InlineResponse20011 - * @version 1.0.3 + * @version 1.4.2 */ class InlineResponse20011 { /** diff --git a/src/model/InlineResponse20012.js b/src/model/InlineResponse20012.js index e9dad306..2d28ce9f 100644 --- a/src/model/InlineResponse20012.js +++ b/src/model/InlineResponse20012.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -17,7 +17,7 @@ import Survey from './Survey'; /** * The InlineResponse20012 model module. * @module model/InlineResponse20012 - * @version 1.0.3 + * @version 1.4.2 */ class InlineResponse20012 { /** diff --git a/src/model/InlineResponse20013.js b/src/model/InlineResponse20013.js index faae97b4..f12926a8 100644 --- a/src/model/InlineResponse20013.js +++ b/src/model/InlineResponse20013.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -17,7 +17,7 @@ import MapWithSensors from './MapWithSensors'; /** * The InlineResponse20013 model module. * @module model/InlineResponse20013 - * @version 1.0.3 + * @version 1.4.2 */ class InlineResponse20013 { /** diff --git a/src/model/InlineResponse20014.js b/src/model/InlineResponse20014.js index d7967988..2f125ca2 100644 --- a/src/model/InlineResponse20014.js +++ b/src/model/InlineResponse20014.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -17,7 +17,7 @@ import SensorAverageSurvey from './SensorAverageSurvey'; /** * The InlineResponse20014 model module. * @module model/InlineResponse20014 - * @version 1.0.3 + * @version 1.4.2 */ class InlineResponse20014 { /** diff --git a/src/model/InlineResponse20015.js b/src/model/InlineResponse20015.js index 97329fdc..14ff03f0 100644 --- a/src/model/InlineResponse20015.js +++ b/src/model/InlineResponse20015.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -16,7 +16,7 @@ import ApiClient from '../ApiClient'; /** * The InlineResponse20015 model module. * @module model/InlineResponse20015 - * @version 1.0.3 + * @version 1.4.2 */ class InlineResponse20015 { /** diff --git a/src/model/InlineResponse20016.js b/src/model/InlineResponse20016.js index 6a10a6b9..5cff0d6e 100644 --- a/src/model/InlineResponse20016.js +++ b/src/model/InlineResponse20016.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -17,7 +17,7 @@ import SurveyWithMaps from './SurveyWithMaps'; /** * The InlineResponse20016 model module. * @module model/InlineResponse20016 - * @version 1.0.3 + * @version 1.4.2 */ class InlineResponse20016 { /** diff --git a/src/model/InlineResponse20017.js b/src/model/InlineResponse20017.js index 29bec805..cfe23541 100644 --- a/src/model/InlineResponse20017.js +++ b/src/model/InlineResponse20017.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -16,7 +16,7 @@ import ApiClient from '../ApiClient'; /** * The InlineResponse20017 model module. * @module model/InlineResponse20017 - * @version 1.0.3 + * @version 1.4.2 */ class InlineResponse20017 { /** diff --git a/src/model/InlineResponse20018.js b/src/model/InlineResponse20018.js index 6b11ceb5..1323a21d 100644 --- a/src/model/InlineResponse20018.js +++ b/src/model/InlineResponse20018.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -17,7 +17,7 @@ import InlineResponse20018Data from './InlineResponse20018Data'; /** * The InlineResponse20018 model module. * @module model/InlineResponse20018 - * @version 1.0.3 + * @version 1.4.2 */ class InlineResponse20018 { /** diff --git a/src/model/InlineResponse20018Data.js b/src/model/InlineResponse20018Data.js index 58bea443..40c1855b 100644 --- a/src/model/InlineResponse20018Data.js +++ b/src/model/InlineResponse20018Data.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -17,7 +17,7 @@ import HistoricalSurveyData from './HistoricalSurveyData'; /** * The InlineResponse20018Data model module. * @module model/InlineResponse20018Data - * @version 1.0.3 + * @version 1.4.2 */ class InlineResponse20018Data { /** diff --git a/src/model/InlineResponse20019.js b/src/model/InlineResponse20019.js index 36d66827..fa0441c7 100644 --- a/src/model/InlineResponse20019.js +++ b/src/model/InlineResponse20019.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -17,7 +17,7 @@ import InlineResponse20019Data from './InlineResponse20019Data'; /** * The InlineResponse20019 model module. * @module model/InlineResponse20019 - * @version 1.0.3 + * @version 1.4.2 */ class InlineResponse20019 { /** diff --git a/src/model/InlineResponse20019Data.js b/src/model/InlineResponse20019Data.js index 2dd26ef4..1c4fe343 100644 --- a/src/model/InlineResponse20019Data.js +++ b/src/model/InlineResponse20019Data.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -17,7 +17,7 @@ import HistoricalSensor from './HistoricalSensor'; /** * The InlineResponse20019Data model module. * @module model/InlineResponse20019Data - * @version 1.0.3 + * @version 1.4.2 */ class InlineResponse20019Data { /** diff --git a/src/model/InlineResponse2002.js b/src/model/InlineResponse2002.js index b67b0a71..826ff910 100644 --- a/src/model/InlineResponse2002.js +++ b/src/model/InlineResponse2002.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -17,7 +17,7 @@ import ModuleDataCoursesModules from './ModuleDataCoursesModules'; /** * The InlineResponse2002 model module. * @module model/InlineResponse2002 - * @version 1.0.3 + * @version 1.4.2 */ class InlineResponse2002 { /** diff --git a/src/model/InlineResponse20020.js b/src/model/InlineResponse20020.js index d087dddd..2b80a1a6 100644 --- a/src/model/InlineResponse20020.js +++ b/src/model/InlineResponse20020.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -17,7 +17,7 @@ import InlineResponse20020Surveys from './InlineResponse20020Surveys'; /** * The InlineResponse20020 model module. * @module model/InlineResponse20020 - * @version 1.0.3 + * @version 1.4.2 */ class InlineResponse20020 { /** diff --git a/src/model/InlineResponse20020Surveys.js b/src/model/InlineResponse20020Surveys.js index aaa820a7..4e78a91e 100644 --- a/src/model/InlineResponse20020Surveys.js +++ b/src/model/InlineResponse20020Surveys.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -17,7 +17,7 @@ import HistoricalSurvey from './HistoricalSurvey'; /** * The InlineResponse20020Surveys model module. * @module model/InlineResponse20020Surveys - * @version 1.0.3 + * @version 1.4.2 */ class InlineResponse20020Surveys { /** diff --git a/src/model/InlineResponse20021.js b/src/model/InlineResponse20021.js index dab13236..42af3628 100644 --- a/src/model/InlineResponse20021.js +++ b/src/model/InlineResponse20021.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -16,7 +16,7 @@ import ApiClient from '../ApiClient'; /** * The InlineResponse20021 model module. * @module model/InlineResponse20021 - * @version 1.0.3 + * @version 1.4.2 */ class InlineResponse20021 { /** diff --git a/src/model/InlineResponse20022.js b/src/model/InlineResponse20022.js index d9db6857..dc6f8d12 100644 --- a/src/model/InlineResponse20022.js +++ b/src/model/InlineResponse20022.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -16,7 +16,7 @@ import ApiClient from '../ApiClient'; /** * The InlineResponse20022 model module. * @module model/InlineResponse20022 - * @version 1.0.3 + * @version 1.4.2 */ class InlineResponse20022 { /** diff --git a/src/model/InlineResponse20023.js b/src/model/InlineResponse20023.js index 03957714..9179ef04 100644 --- a/src/model/InlineResponse20023.js +++ b/src/model/InlineResponse20023.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -17,7 +17,7 @@ import InlineResponse20023Data from './InlineResponse20023Data'; /** * The InlineResponse20023 model module. * @module model/InlineResponse20023 - * @version 1.0.3 + * @version 1.4.2 */ class InlineResponse20023 { /** diff --git a/src/model/InlineResponse20023Data.js b/src/model/InlineResponse20023Data.js index d27f1a2f..1696c205 100644 --- a/src/model/InlineResponse20023Data.js +++ b/src/model/InlineResponse20023Data.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -16,7 +16,7 @@ import ApiClient from '../ApiClient'; /** * The InlineResponse20023Data model module. * @module model/InlineResponse20023Data - * @version 1.0.3 + * @version 1.4.2 */ class InlineResponse20023Data { /** diff --git a/src/model/InlineResponse20024.js b/src/model/InlineResponse20024.js index 2a66c070..dd9878d9 100644 --- a/src/model/InlineResponse20024.js +++ b/src/model/InlineResponse20024.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -17,7 +17,7 @@ import InlineResponse20024Data from './InlineResponse20024Data'; /** * The InlineResponse20024 model module. * @module model/InlineResponse20024 - * @version 1.0.3 + * @version 1.4.2 */ class InlineResponse20024 { /** diff --git a/src/model/InlineResponse20024Data.js b/src/model/InlineResponse20024Data.js index 9e11f5a7..004fc1ee 100644 --- a/src/model/InlineResponse20024Data.js +++ b/src/model/InlineResponse20024Data.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -16,7 +16,7 @@ import ApiClient from '../ApiClient'; /** * The InlineResponse20024Data model module. * @module model/InlineResponse20024Data - * @version 1.0.3 + * @version 1.4.2 */ class InlineResponse20024Data { /** diff --git a/src/model/InlineResponse20025.js b/src/model/InlineResponse20025.js index 8e9aa34c..abb23cf6 100644 --- a/src/model/InlineResponse20025.js +++ b/src/model/InlineResponse20025.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -16,7 +16,7 @@ import ApiClient from '../ApiClient'; /** * The InlineResponse20025 model module. * @module model/InlineResponse20025 - * @version 1.0.3 + * @version 1.4.2 */ class InlineResponse20025 { /** diff --git a/src/model/InlineResponse20026.js b/src/model/InlineResponse20026.js index 49d73ffb..e9bf1b35 100644 --- a/src/model/InlineResponse20026.js +++ b/src/model/InlineResponse20026.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -17,7 +17,7 @@ import InlineResponse20026Data from './InlineResponse20026Data'; /** * The InlineResponse20026 model module. * @module model/InlineResponse20026 - * @version 1.0.3 + * @version 1.4.2 */ class InlineResponse20026 { /** diff --git a/src/model/InlineResponse20026Data.js b/src/model/InlineResponse20026Data.js index 7562fb9e..61d8a3ac 100644 --- a/src/model/InlineResponse20026Data.js +++ b/src/model/InlineResponse20026Data.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -16,7 +16,7 @@ import ApiClient from '../ApiClient'; /** * The InlineResponse20026Data model module. * @module model/InlineResponse20026Data - * @version 1.0.3 + * @version 1.4.2 */ class InlineResponse20026Data { /** diff --git a/src/model/InlineResponse20027.js b/src/model/InlineResponse20027.js new file mode 100644 index 00000000..47f85496 --- /dev/null +++ b/src/model/InlineResponse20027.js @@ -0,0 +1,80 @@ +/** + * UCL API + * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` + * + * The version of the OpenAPI document: 1.4.2 + * Contact: isd.apiteam@ucl.ac.uk + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + * + */ + +import ApiClient from '../ApiClient'; +import LibcalLocation from './LibcalLocation'; + +/** + * The InlineResponse20027 model module. + * @module model/InlineResponse20027 + * @version 1.4.2 + */ +class InlineResponse20027 { + /** + * Constructs a new InlineResponse20027. + * @alias module:model/InlineResponse20027 + */ + constructor() { + + InlineResponse20027.initialize(this); + } + + /** + * Initializes the fields of this object. + * This method is used by the constructors of any subclasses, in order to implement multiple inheritance (mix-ins). + * Only for internal use. + */ + static initialize(obj) { + } + + /** + * Constructs a InlineResponse20027 from a plain JavaScript object, optionally creating a new instance. + * Copies all relevant properties from data to obj if supplied or a new instance if not. + * @param {Object} data The plain JavaScript object bearing properties of interest. + * @param {module:model/InlineResponse20027} obj Optional instance to populate. + * @return {module:model/InlineResponse20027} The populated InlineResponse20027 instance. + */ + static constructFromObject(data, obj) { + if (data) { + obj = obj || new InlineResponse20027(); + + if (data.hasOwnProperty('ok')) { + obj['ok'] = ApiClient.convertToType(data['ok'], 'Boolean'); + } + if (data.hasOwnProperty('data')) { + obj['data'] = ApiClient.convertToType(data['data'], [LibcalLocation]); + } + } + return obj; + } + + +} + +/** + * @member {Boolean} ok + */ +InlineResponse20027.prototype['ok'] = undefined; + +/** + * @member {Array.} data + */ +InlineResponse20027.prototype['data'] = undefined; + + + + + + +export default InlineResponse20027; + diff --git a/src/model/InlineResponse20028.js b/src/model/InlineResponse20028.js new file mode 100644 index 00000000..51e9e1e5 --- /dev/null +++ b/src/model/InlineResponse20028.js @@ -0,0 +1,80 @@ +/** + * UCL API + * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` + * + * The version of the OpenAPI document: 1.4.2 + * Contact: isd.apiteam@ucl.ac.uk + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + * + */ + +import ApiClient from '../ApiClient'; +import LibcalLocationBase from './LibcalLocationBase'; + +/** + * The InlineResponse20028 model module. + * @module model/InlineResponse20028 + * @version 1.4.2 + */ +class InlineResponse20028 { + /** + * Constructs a new InlineResponse20028. + * @alias module:model/InlineResponse20028 + */ + constructor() { + + InlineResponse20028.initialize(this); + } + + /** + * Initializes the fields of this object. + * This method is used by the constructors of any subclasses, in order to implement multiple inheritance (mix-ins). + * Only for internal use. + */ + static initialize(obj) { + } + + /** + * Constructs a InlineResponse20028 from a plain JavaScript object, optionally creating a new instance. + * Copies all relevant properties from data to obj if supplied or a new instance if not. + * @param {Object} data The plain JavaScript object bearing properties of interest. + * @param {module:model/InlineResponse20028} obj Optional instance to populate. + * @return {module:model/InlineResponse20028} The populated InlineResponse20028 instance. + */ + static constructFromObject(data, obj) { + if (data) { + obj = obj || new InlineResponse20028(); + + if (data.hasOwnProperty('ok')) { + obj['ok'] = ApiClient.convertToType(data['ok'], 'Boolean'); + } + if (data.hasOwnProperty('categories')) { + obj['categories'] = ApiClient.convertToType(data['categories'], [LibcalLocationBase]); + } + } + return obj; + } + + +} + +/** + * @member {Boolean} ok + */ +InlineResponse20028.prototype['ok'] = undefined; + +/** + * @member {Array.} categories + */ +InlineResponse20028.prototype['categories'] = undefined; + + + + + + +export default InlineResponse20028; + diff --git a/src/model/InlineResponse20029.js b/src/model/InlineResponse20029.js new file mode 100644 index 00000000..c0fe25fd --- /dev/null +++ b/src/model/InlineResponse20029.js @@ -0,0 +1,80 @@ +/** + * UCL API + * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` + * + * The version of the OpenAPI document: 1.4.2 + * Contact: isd.apiteam@ucl.ac.uk + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + * + */ + +import ApiClient from '../ApiClient'; +import InlineResponse20029Categories from './InlineResponse20029Categories'; + +/** + * The InlineResponse20029 model module. + * @module model/InlineResponse20029 + * @version 1.4.2 + */ +class InlineResponse20029 { + /** + * Constructs a new InlineResponse20029. + * @alias module:model/InlineResponse20029 + */ + constructor() { + + InlineResponse20029.initialize(this); + } + + /** + * Initializes the fields of this object. + * This method is used by the constructors of any subclasses, in order to implement multiple inheritance (mix-ins). + * Only for internal use. + */ + static initialize(obj) { + } + + /** + * Constructs a InlineResponse20029 from a plain JavaScript object, optionally creating a new instance. + * Copies all relevant properties from data to obj if supplied or a new instance if not. + * @param {Object} data The plain JavaScript object bearing properties of interest. + * @param {module:model/InlineResponse20029} obj Optional instance to populate. + * @return {module:model/InlineResponse20029} The populated InlineResponse20029 instance. + */ + static constructFromObject(data, obj) { + if (data) { + obj = obj || new InlineResponse20029(); + + if (data.hasOwnProperty('ok')) { + obj['ok'] = ApiClient.convertToType(data['ok'], 'Boolean'); + } + if (data.hasOwnProperty('categories')) { + obj['categories'] = ApiClient.convertToType(data['categories'], [InlineResponse20029Categories]); + } + } + return obj; + } + + +} + +/** + * @member {Boolean} ok + */ +InlineResponse20029.prototype['ok'] = undefined; + +/** + * @member {Array.} categories + */ +InlineResponse20029.prototype['categories'] = undefined; + + + + + + +export default InlineResponse20029; + diff --git a/src/model/InlineResponse20029Categories.js b/src/model/InlineResponse20029Categories.js new file mode 100644 index 00000000..9c83c2e8 --- /dev/null +++ b/src/model/InlineResponse20029Categories.js @@ -0,0 +1,98 @@ +/** + * UCL API + * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` + * + * The version of the OpenAPI document: 1.4.2 + * Contact: isd.apiteam@ucl.ac.uk + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + * + */ + +import ApiClient from '../ApiClient'; + +/** + * The InlineResponse20029Categories model module. + * @module model/InlineResponse20029Categories + * @version 1.4.2 + */ +class InlineResponse20029Categories { + /** + * Constructs a new InlineResponse20029Categories. + * @alias module:model/InlineResponse20029Categories + */ + constructor() { + + InlineResponse20029Categories.initialize(this); + } + + /** + * Initializes the fields of this object. + * This method is used by the constructors of any subclasses, in order to implement multiple inheritance (mix-ins). + * Only for internal use. + */ + static initialize(obj) { + } + + /** + * Constructs a InlineResponse20029Categories from a plain JavaScript object, optionally creating a new instance. + * Copies all relevant properties from data to obj if supplied or a new instance if not. + * @param {Object} data The plain JavaScript object bearing properties of interest. + * @param {module:model/InlineResponse20029Categories} obj Optional instance to populate. + * @return {module:model/InlineResponse20029Categories} The populated InlineResponse20029Categories instance. + */ + static constructFromObject(data, obj) { + if (data) { + obj = obj || new InlineResponse20029Categories(); + + if (data.hasOwnProperty('cid')) { + obj['cid'] = ApiClient.convertToType(data['cid'], 'Number'); + } + if (data.hasOwnProperty('formid')) { + obj['formid'] = ApiClient.convertToType(data['formid'], 'Number'); + } + if (data.hasOwnProperty('public')) { + obj['public'] = ApiClient.convertToType(data['public'], 'Number'); + } + if (data.hasOwnProperty('items')) { + obj['items'] = ApiClient.convertToType(data['items'], ['Number']); + } + } + return obj; + } + + +} + +/** + * LibCal category ID denoting a category assigned to a particular space + * @member {Number} cid + */ +InlineResponse20029Categories.prototype['cid'] = undefined; + +/** + * LibCal booking form ID + * @member {Number} formid + */ +InlineResponse20029Categories.prototype['formid'] = undefined; + +/** + * 1 if the category of spaces is publicly-bookable, 0 if it is not + * @member {Number} public + */ +InlineResponse20029Categories.prototype['public'] = undefined; + +/** + * @member {Array.} items + */ +InlineResponse20029Categories.prototype['items'] = undefined; + + + + + + +export default InlineResponse20029Categories; + diff --git a/src/model/InlineResponse2003.js b/src/model/InlineResponse2003.js index bd7d064f..7b97542f 100644 --- a/src/model/InlineResponse2003.js +++ b/src/model/InlineResponse2003.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -17,7 +17,7 @@ import Course from './Course'; /** * The InlineResponse2003 model module. * @module model/InlineResponse2003 - * @version 1.0.3 + * @version 1.4.2 */ class InlineResponse2003 { /** diff --git a/src/model/InlineResponse20030.js b/src/model/InlineResponse20030.js new file mode 100644 index 00000000..c868522f --- /dev/null +++ b/src/model/InlineResponse20030.js @@ -0,0 +1,80 @@ +/** + * UCL API + * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` + * + * The version of the OpenAPI document: 1.4.2 + * Contact: isd.apiteam@ucl.ac.uk + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + * + */ + +import ApiClient from '../ApiClient'; +import LibcalForm from './LibcalForm'; + +/** + * The InlineResponse20030 model module. + * @module model/InlineResponse20030 + * @version 1.4.2 + */ +class InlineResponse20030 { + /** + * Constructs a new InlineResponse20030. + * @alias module:model/InlineResponse20030 + */ + constructor() { + + InlineResponse20030.initialize(this); + } + + /** + * Initializes the fields of this object. + * This method is used by the constructors of any subclasses, in order to implement multiple inheritance (mix-ins). + * Only for internal use. + */ + static initialize(obj) { + } + + /** + * Constructs a InlineResponse20030 from a plain JavaScript object, optionally creating a new instance. + * Copies all relevant properties from data to obj if supplied or a new instance if not. + * @param {Object} data The plain JavaScript object bearing properties of interest. + * @param {module:model/InlineResponse20030} obj Optional instance to populate. + * @return {module:model/InlineResponse20030} The populated InlineResponse20030 instance. + */ + static constructFromObject(data, obj) { + if (data) { + obj = obj || new InlineResponse20030(); + + if (data.hasOwnProperty('ok')) { + obj['ok'] = ApiClient.convertToType(data['ok'], 'Boolean'); + } + if (data.hasOwnProperty('forms')) { + obj['forms'] = ApiClient.convertToType(data['forms'], [LibcalForm]); + } + } + return obj; + } + + +} + +/** + * @member {Boolean} ok + */ +InlineResponse20030.prototype['ok'] = undefined; + +/** + * @member {Array.} forms + */ +InlineResponse20030.prototype['forms'] = undefined; + + + + + + +export default InlineResponse20030; + diff --git a/src/model/InlineResponse20031.js b/src/model/InlineResponse20031.js new file mode 100644 index 00000000..2dadcbaa --- /dev/null +++ b/src/model/InlineResponse20031.js @@ -0,0 +1,80 @@ +/** + * UCL API + * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` + * + * The version of the OpenAPI document: 1.4.2 + * Contact: isd.apiteam@ucl.ac.uk + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + * + */ + +import ApiClient from '../ApiClient'; +import LibcalFormField from './LibcalFormField'; + +/** + * The InlineResponse20031 model module. + * @module model/InlineResponse20031 + * @version 1.4.2 + */ +class InlineResponse20031 { + /** + * Constructs a new InlineResponse20031. + * @alias module:model/InlineResponse20031 + */ + constructor() { + + InlineResponse20031.initialize(this); + } + + /** + * Initializes the fields of this object. + * This method is used by the constructors of any subclasses, in order to implement multiple inheritance (mix-ins). + * Only for internal use. + */ + static initialize(obj) { + } + + /** + * Constructs a InlineResponse20031 from a plain JavaScript object, optionally creating a new instance. + * Copies all relevant properties from data to obj if supplied or a new instance if not. + * @param {Object} data The plain JavaScript object bearing properties of interest. + * @param {module:model/InlineResponse20031} obj Optional instance to populate. + * @return {module:model/InlineResponse20031} The populated InlineResponse20031 instance. + */ + static constructFromObject(data, obj) { + if (data) { + obj = obj || new InlineResponse20031(); + + if (data.hasOwnProperty('ok')) { + obj['ok'] = ApiClient.convertToType(data['ok'], 'Boolean'); + } + if (data.hasOwnProperty('questions')) { + obj['questions'] = ApiClient.convertToType(data['questions'], [LibcalFormField]); + } + } + return obj; + } + + +} + +/** + * @member {Boolean} ok + */ +InlineResponse20031.prototype['ok'] = undefined; + +/** + * @member {Array.} questions + */ +InlineResponse20031.prototype['questions'] = undefined; + + + + + + +export default InlineResponse20031; + diff --git a/src/model/InlineResponse20032.js b/src/model/InlineResponse20032.js new file mode 100644 index 00000000..e1a85f0e --- /dev/null +++ b/src/model/InlineResponse20032.js @@ -0,0 +1,80 @@ +/** + * UCL API + * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` + * + * The version of the OpenAPI document: 1.4.2 + * Contact: isd.apiteam@ucl.ac.uk + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + * + */ + +import ApiClient from '../ApiClient'; +import LibcalSpaceBase from './LibcalSpaceBase'; + +/** + * The InlineResponse20032 model module. + * @module model/InlineResponse20032 + * @version 1.4.2 + */ +class InlineResponse20032 { + /** + * Constructs a new InlineResponse20032. + * @alias module:model/InlineResponse20032 + */ + constructor() { + + InlineResponse20032.initialize(this); + } + + /** + * Initializes the fields of this object. + * This method is used by the constructors of any subclasses, in order to implement multiple inheritance (mix-ins). + * Only for internal use. + */ + static initialize(obj) { + } + + /** + * Constructs a InlineResponse20032 from a plain JavaScript object, optionally creating a new instance. + * Copies all relevant properties from data to obj if supplied or a new instance if not. + * @param {Object} data The plain JavaScript object bearing properties of interest. + * @param {module:model/InlineResponse20032} obj Optional instance to populate. + * @return {module:model/InlineResponse20032} The populated InlineResponse20032 instance. + */ + static constructFromObject(data, obj) { + if (data) { + obj = obj || new InlineResponse20032(); + + if (data.hasOwnProperty('ok')) { + obj['ok'] = ApiClient.convertToType(data['ok'], 'Boolean'); + } + if (data.hasOwnProperty('questions')) { + obj['questions'] = ApiClient.convertToType(data['questions'], [LibcalSpaceBase]); + } + } + return obj; + } + + +} + +/** + * @member {Boolean} ok + */ +InlineResponse20032.prototype['ok'] = undefined; + +/** + * @member {Array.} questions + */ +InlineResponse20032.prototype['questions'] = undefined; + + + + + + +export default InlineResponse20032; + diff --git a/src/model/InlineResponse20033.js b/src/model/InlineResponse20033.js new file mode 100644 index 00000000..52c06796 --- /dev/null +++ b/src/model/InlineResponse20033.js @@ -0,0 +1,79 @@ +/** + * UCL API + * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` + * + * The version of the OpenAPI document: 1.4.2 + * Contact: isd.apiteam@ucl.ac.uk + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + * + */ + +import ApiClient from '../ApiClient'; + +/** + * The InlineResponse20033 model module. + * @module model/InlineResponse20033 + * @version 1.4.2 + */ +class InlineResponse20033 { + /** + * Constructs a new InlineResponse20033. + * @alias module:model/InlineResponse20033 + */ + constructor() { + + InlineResponse20033.initialize(this); + } + + /** + * Initializes the fields of this object. + * This method is used by the constructors of any subclasses, in order to implement multiple inheritance (mix-ins). + * Only for internal use. + */ + static initialize(obj) { + } + + /** + * Constructs a InlineResponse20033 from a plain JavaScript object, optionally creating a new instance. + * Copies all relevant properties from data to obj if supplied or a new instance if not. + * @param {Object} data The plain JavaScript object bearing properties of interest. + * @param {module:model/InlineResponse20033} obj Optional instance to populate. + * @return {module:model/InlineResponse20033} The populated InlineResponse20033 instance. + */ + static constructFromObject(data, obj) { + if (data) { + obj = obj || new InlineResponse20033(); + + if (data.hasOwnProperty('ok')) { + obj['ok'] = ApiClient.convertToType(data['ok'], 'Boolean'); + } + if (data.hasOwnProperty('categories')) { + obj['categories'] = ApiClient.convertToType(data['categories'], [Object]); + } + } + return obj; + } + + +} + +/** + * @member {Boolean} ok + */ +InlineResponse20033.prototype['ok'] = undefined; + +/** + * @member {Array.} categories + */ +InlineResponse20033.prototype['categories'] = undefined; + + + + + + +export default InlineResponse20033; + diff --git a/src/model/InlineResponse20034.js b/src/model/InlineResponse20034.js new file mode 100644 index 00000000..7298b10c --- /dev/null +++ b/src/model/InlineResponse20034.js @@ -0,0 +1,79 @@ +/** + * UCL API + * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` + * + * The version of the OpenAPI document: 1.4.2 + * Contact: isd.apiteam@ucl.ac.uk + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + * + */ + +import ApiClient from '../ApiClient'; + +/** + * The InlineResponse20034 model module. + * @module model/InlineResponse20034 + * @version 1.4.2 + */ +class InlineResponse20034 { + /** + * Constructs a new InlineResponse20034. + * @alias module:model/InlineResponse20034 + */ + constructor() { + + InlineResponse20034.initialize(this); + } + + /** + * Initializes the fields of this object. + * This method is used by the constructors of any subclasses, in order to implement multiple inheritance (mix-ins). + * Only for internal use. + */ + static initialize(obj) { + } + + /** + * Constructs a InlineResponse20034 from a plain JavaScript object, optionally creating a new instance. + * Copies all relevant properties from data to obj if supplied or a new instance if not. + * @param {Object} data The plain JavaScript object bearing properties of interest. + * @param {module:model/InlineResponse20034} obj Optional instance to populate. + * @return {module:model/InlineResponse20034} The populated InlineResponse20034 instance. + */ + static constructFromObject(data, obj) { + if (data) { + obj = obj || new InlineResponse20034(); + + if (data.hasOwnProperty('ok')) { + obj['ok'] = ApiClient.convertToType(data['ok'], 'Boolean'); + } + if (data.hasOwnProperty('data')) { + obj['data'] = ApiClient.convertToType(data['data'], Object); + } + } + return obj; + } + + +} + +/** + * @member {Boolean} ok + */ +InlineResponse20034.prototype['ok'] = undefined; + +/** + * @member {Object} data + */ +InlineResponse20034.prototype['data'] = undefined; + + + + + + +export default InlineResponse20034; + diff --git a/src/model/InlineResponse20035.js b/src/model/InlineResponse20035.js new file mode 100644 index 00000000..b346564e --- /dev/null +++ b/src/model/InlineResponse20035.js @@ -0,0 +1,80 @@ +/** + * UCL API + * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` + * + * The version of the OpenAPI document: 1.4.2 + * Contact: isd.apiteam@ucl.ac.uk + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + * + */ + +import ApiClient from '../ApiClient'; +import LibcalSeat from './LibcalSeat'; + +/** + * The InlineResponse20035 model module. + * @module model/InlineResponse20035 + * @version 1.4.2 + */ +class InlineResponse20035 { + /** + * Constructs a new InlineResponse20035. + * @alias module:model/InlineResponse20035 + */ + constructor() { + + InlineResponse20035.initialize(this); + } + + /** + * Initializes the fields of this object. + * This method is used by the constructors of any subclasses, in order to implement multiple inheritance (mix-ins). + * Only for internal use. + */ + static initialize(obj) { + } + + /** + * Constructs a InlineResponse20035 from a plain JavaScript object, optionally creating a new instance. + * Copies all relevant properties from data to obj if supplied or a new instance if not. + * @param {Object} data The plain JavaScript object bearing properties of interest. + * @param {module:model/InlineResponse20035} obj Optional instance to populate. + * @return {module:model/InlineResponse20035} The populated InlineResponse20035 instance. + */ + static constructFromObject(data, obj) { + if (data) { + obj = obj || new InlineResponse20035(); + + if (data.hasOwnProperty('ok')) { + obj['ok'] = ApiClient.convertToType(data['ok'], 'Boolean'); + } + if (data.hasOwnProperty('seats')) { + obj['seats'] = ApiClient.convertToType(data['seats'], [LibcalSeat]); + } + } + return obj; + } + + +} + +/** + * @member {Boolean} ok + */ +InlineResponse20035.prototype['ok'] = undefined; + +/** + * @member {Array.} seats + */ +InlineResponse20035.prototype['seats'] = undefined; + + + + + + +export default InlineResponse20035; + diff --git a/src/model/InlineResponse20036.js b/src/model/InlineResponse20036.js new file mode 100644 index 00000000..95579899 --- /dev/null +++ b/src/model/InlineResponse20036.js @@ -0,0 +1,80 @@ +/** + * UCL API + * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` + * + * The version of the OpenAPI document: 1.4.2 + * Contact: isd.apiteam@ucl.ac.uk + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + * + */ + +import ApiClient from '../ApiClient'; +import LibcalSeat from './LibcalSeat'; + +/** + * The InlineResponse20036 model module. + * @module model/InlineResponse20036 + * @version 1.4.2 + */ +class InlineResponse20036 { + /** + * Constructs a new InlineResponse20036. + * @alias module:model/InlineResponse20036 + */ + constructor() { + + InlineResponse20036.initialize(this); + } + + /** + * Initializes the fields of this object. + * This method is used by the constructors of any subclasses, in order to implement multiple inheritance (mix-ins). + * Only for internal use. + */ + static initialize(obj) { + } + + /** + * Constructs a InlineResponse20036 from a plain JavaScript object, optionally creating a new instance. + * Copies all relevant properties from data to obj if supplied or a new instance if not. + * @param {Object} data The plain JavaScript object bearing properties of interest. + * @param {module:model/InlineResponse20036} obj Optional instance to populate. + * @return {module:model/InlineResponse20036} The populated InlineResponse20036 instance. + */ + static constructFromObject(data, obj) { + if (data) { + obj = obj || new InlineResponse20036(); + + if (data.hasOwnProperty('ok')) { + obj['ok'] = ApiClient.convertToType(data['ok'], 'Boolean'); + } + if (data.hasOwnProperty('seat')) { + obj['seat'] = LibcalSeat.constructFromObject(data['seat']); + } + } + return obj; + } + + +} + +/** + * @member {Boolean} ok + */ +InlineResponse20036.prototype['ok'] = undefined; + +/** + * @member {module:model/LibcalSeat} seat + */ +InlineResponse20036.prototype['seat'] = undefined; + + + + + + +export default InlineResponse20036; + diff --git a/src/model/InlineResponse20037.js b/src/model/InlineResponse20037.js new file mode 100644 index 00000000..93b6077a --- /dev/null +++ b/src/model/InlineResponse20037.js @@ -0,0 +1,80 @@ +/** + * UCL API + * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` + * + * The version of the OpenAPI document: 1.4.2 + * Contact: isd.apiteam@ucl.ac.uk + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + * + */ + +import ApiClient from '../ApiClient'; +import LibcalZone from './LibcalZone'; + +/** + * The InlineResponse20037 model module. + * @module model/InlineResponse20037 + * @version 1.4.2 + */ +class InlineResponse20037 { + /** + * Constructs a new InlineResponse20037. + * @alias module:model/InlineResponse20037 + */ + constructor() { + + InlineResponse20037.initialize(this); + } + + /** + * Initializes the fields of this object. + * This method is used by the constructors of any subclasses, in order to implement multiple inheritance (mix-ins). + * Only for internal use. + */ + static initialize(obj) { + } + + /** + * Constructs a InlineResponse20037 from a plain JavaScript object, optionally creating a new instance. + * Copies all relevant properties from data to obj if supplied or a new instance if not. + * @param {Object} data The plain JavaScript object bearing properties of interest. + * @param {module:model/InlineResponse20037} obj Optional instance to populate. + * @return {module:model/InlineResponse20037} The populated InlineResponse20037 instance. + */ + static constructFromObject(data, obj) { + if (data) { + obj = obj || new InlineResponse20037(); + + if (data.hasOwnProperty('ok')) { + obj['ok'] = ApiClient.convertToType(data['ok'], 'Boolean'); + } + if (data.hasOwnProperty('zones')) { + obj['zones'] = ApiClient.convertToType(data['zones'], [LibcalZone]); + } + } + return obj; + } + + +} + +/** + * @member {Boolean} ok + */ +InlineResponse20037.prototype['ok'] = undefined; + +/** + * @member {Array.} zones + */ +InlineResponse20037.prototype['zones'] = undefined; + + + + + + +export default InlineResponse20037; + diff --git a/src/model/InlineResponse20038.js b/src/model/InlineResponse20038.js new file mode 100644 index 00000000..685927e8 --- /dev/null +++ b/src/model/InlineResponse20038.js @@ -0,0 +1,89 @@ +/** + * UCL API + * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` + * + * The version of the OpenAPI document: 1.4.2 + * Contact: isd.apiteam@ucl.ac.uk + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + * + */ + +import ApiClient from '../ApiClient'; +import LibcalZone from './LibcalZone'; + +/** + * The InlineResponse20038 model module. + * @module model/InlineResponse20038 + * @version 1.4.2 + */ +class InlineResponse20038 { + /** + * Constructs a new InlineResponse20038. + * @alias module:model/InlineResponse20038 + */ + constructor() { + + InlineResponse20038.initialize(this); + } + + /** + * Initializes the fields of this object. + * This method is used by the constructors of any subclasses, in order to implement multiple inheritance (mix-ins). + * Only for internal use. + */ + static initialize(obj) { + } + + /** + * Constructs a InlineResponse20038 from a plain JavaScript object, optionally creating a new instance. + * Copies all relevant properties from data to obj if supplied or a new instance if not. + * @param {Object} data The plain JavaScript object bearing properties of interest. + * @param {module:model/InlineResponse20038} obj Optional instance to populate. + * @return {module:model/InlineResponse20038} The populated InlineResponse20038 instance. + */ + static constructFromObject(data, obj) { + if (data) { + obj = obj || new InlineResponse20038(); + + if (data.hasOwnProperty('ok')) { + obj['ok'] = ApiClient.convertToType(data['ok'], 'Boolean'); + } + if (data.hasOwnProperty('error')) { + obj['error'] = ApiClient.convertToType(data['error'], 'String'); + } + if (data.hasOwnProperty('zone')) { + obj['zone'] = ApiClient.convertToType(data['zone'], LibcalZone); + } + } + return obj; + } + + +} + +/** + * @member {Boolean} ok + */ +InlineResponse20038.prototype['ok'] = undefined; + +/** + * Will be returned if there is an error retrieving the given LibCal space, e.g. if the space ID provided is invalid + * @member {String} error + */ +InlineResponse20038.prototype['error'] = undefined; + +/** + * @member {module:model/LibcalZone} zone + */ +InlineResponse20038.prototype['zone'] = undefined; + + + + + + +export default InlineResponse20038; + diff --git a/src/model/InlineResponse20039.js b/src/model/InlineResponse20039.js new file mode 100644 index 00000000..754beb51 --- /dev/null +++ b/src/model/InlineResponse20039.js @@ -0,0 +1,80 @@ +/** + * UCL API + * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` + * + * The version of the OpenAPI document: 1.4.2 + * Contact: isd.apiteam@ucl.ac.uk + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + * + */ + +import ApiClient from '../ApiClient'; +import LibcalSeatBooking from './LibcalSeatBooking'; + +/** + * The InlineResponse20039 model module. + * @module model/InlineResponse20039 + * @version 1.4.2 + */ +class InlineResponse20039 { + /** + * Constructs a new InlineResponse20039. + * @alias module:model/InlineResponse20039 + */ + constructor() { + + InlineResponse20039.initialize(this); + } + + /** + * Initializes the fields of this object. + * This method is used by the constructors of any subclasses, in order to implement multiple inheritance (mix-ins). + * Only for internal use. + */ + static initialize(obj) { + } + + /** + * Constructs a InlineResponse20039 from a plain JavaScript object, optionally creating a new instance. + * Copies all relevant properties from data to obj if supplied or a new instance if not. + * @param {Object} data The plain JavaScript object bearing properties of interest. + * @param {module:model/InlineResponse20039} obj Optional instance to populate. + * @return {module:model/InlineResponse20039} The populated InlineResponse20039 instance. + */ + static constructFromObject(data, obj) { + if (data) { + obj = obj || new InlineResponse20039(); + + if (data.hasOwnProperty('ok')) { + obj['ok'] = ApiClient.convertToType(data['ok'], 'Boolean'); + } + if (data.hasOwnProperty('bookings')) { + obj['bookings'] = ApiClient.convertToType(data['bookings'], [LibcalSeatBooking]); + } + } + return obj; + } + + +} + +/** + * @member {Boolean} ok + */ +InlineResponse20039.prototype['ok'] = undefined; + +/** + * @member {Array.} bookings + */ +InlineResponse20039.prototype['bookings'] = undefined; + + + + + + +export default InlineResponse20039; + diff --git a/src/model/InlineResponse2004.js b/src/model/InlineResponse2004.js index 83fa4e70..23d1f5ef 100644 --- a/src/model/InlineResponse2004.js +++ b/src/model/InlineResponse2004.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -16,7 +16,7 @@ import ApiClient from '../ApiClient'; /** * The InlineResponse2004 model module. * @module model/InlineResponse2004 - * @version 1.0.3 + * @version 1.4.2 */ class InlineResponse2004 { /** diff --git a/src/model/InlineResponse20040.js b/src/model/InlineResponse20040.js new file mode 100644 index 00000000..d87c74fa --- /dev/null +++ b/src/model/InlineResponse20040.js @@ -0,0 +1,80 @@ +/** + * UCL API + * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` + * + * The version of the OpenAPI document: 1.4.2 + * Contact: isd.apiteam@ucl.ac.uk + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + * + */ + +import ApiClient from '../ApiClient'; +import LibcalPersonalSeatBooking from './LibcalPersonalSeatBooking'; + +/** + * The InlineResponse20040 model module. + * @module model/InlineResponse20040 + * @version 1.4.2 + */ +class InlineResponse20040 { + /** + * Constructs a new InlineResponse20040. + * @alias module:model/InlineResponse20040 + */ + constructor() { + + InlineResponse20040.initialize(this); + } + + /** + * Initializes the fields of this object. + * This method is used by the constructors of any subclasses, in order to implement multiple inheritance (mix-ins). + * Only for internal use. + */ + static initialize(obj) { + } + + /** + * Constructs a InlineResponse20040 from a plain JavaScript object, optionally creating a new instance. + * Copies all relevant properties from data to obj if supplied or a new instance if not. + * @param {Object} data The plain JavaScript object bearing properties of interest. + * @param {module:model/InlineResponse20040} obj Optional instance to populate. + * @return {module:model/InlineResponse20040} The populated InlineResponse20040 instance. + */ + static constructFromObject(data, obj) { + if (data) { + obj = obj || new InlineResponse20040(); + + if (data.hasOwnProperty('ok')) { + obj['ok'] = ApiClient.convertToType(data['ok'], 'Boolean'); + } + if (data.hasOwnProperty('bookings')) { + obj['bookings'] = ApiClient.convertToType(data['bookings'], [LibcalPersonalSeatBooking]); + } + } + return obj; + } + + +} + +/** + * @member {Boolean} ok + */ +InlineResponse20040.prototype['ok'] = undefined; + +/** + * @member {Array.} bookings + */ +InlineResponse20040.prototype['bookings'] = undefined; + + + + + + +export default InlineResponse20040; + diff --git a/src/model/InlineResponse20041.js b/src/model/InlineResponse20041.js new file mode 100644 index 00000000..d7be9354 --- /dev/null +++ b/src/model/InlineResponse20041.js @@ -0,0 +1,88 @@ +/** + * UCL API + * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` + * + * The version of the OpenAPI document: 1.4.2 + * Contact: isd.apiteam@ucl.ac.uk + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + * + */ + +import ApiClient from '../ApiClient'; + +/** + * The InlineResponse20041 model module. + * @module model/InlineResponse20041 + * @version 1.4.2 + */ +class InlineResponse20041 { + /** + * Constructs a new InlineResponse20041. + * @alias module:model/InlineResponse20041 + */ + constructor() { + + InlineResponse20041.initialize(this); + } + + /** + * Initializes the fields of this object. + * This method is used by the constructors of any subclasses, in order to implement multiple inheritance (mix-ins). + * Only for internal use. + */ + static initialize(obj) { + } + + /** + * Constructs a InlineResponse20041 from a plain JavaScript object, optionally creating a new instance. + * Copies all relevant properties from data to obj if supplied or a new instance if not. + * @param {Object} data The plain JavaScript object bearing properties of interest. + * @param {module:model/InlineResponse20041} obj Optional instance to populate. + * @return {module:model/InlineResponse20041} The populated InlineResponse20041 instance. + */ + static constructFromObject(data, obj) { + if (data) { + obj = obj || new InlineResponse20041(); + + if (data.hasOwnProperty('ok')) { + obj['ok'] = ApiClient.convertToType(data['ok'], 'Boolean'); + } + if (data.hasOwnProperty('error')) { + obj['error'] = ApiClient.convertToType(data['error'], Object); + } + if (data.hasOwnProperty('bookings')) { + obj['bookings'] = ApiClient.convertToType(data['bookings'], Object); + } + } + return obj; + } + + +} + +/** + * @member {Boolean} ok + */ +InlineResponse20041.prototype['ok'] = undefined; + +/** + * Will only be returned if there are errors + * @member {Object} error + */ +InlineResponse20041.prototype['error'] = undefined; + +/** + * @member {Object} bookings + */ +InlineResponse20041.prototype['bookings'] = undefined; + + + + + + +export default InlineResponse20041; + diff --git a/src/model/InlineResponse20042.js b/src/model/InlineResponse20042.js new file mode 100644 index 00000000..1f744f14 --- /dev/null +++ b/src/model/InlineResponse20042.js @@ -0,0 +1,79 @@ +/** + * UCL API + * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` + * + * The version of the OpenAPI document: 1.4.2 + * Contact: isd.apiteam@ucl.ac.uk + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + * + */ + +import ApiClient from '../ApiClient'; + +/** + * The InlineResponse20042 model module. + * @module model/InlineResponse20042 + * @version 1.4.2 + */ +class InlineResponse20042 { + /** + * Constructs a new InlineResponse20042. + * @alias module:model/InlineResponse20042 + */ + constructor() { + + InlineResponse20042.initialize(this); + } + + /** + * Initializes the fields of this object. + * This method is used by the constructors of any subclasses, in order to implement multiple inheritance (mix-ins). + * Only for internal use. + */ + static initialize(obj) { + } + + /** + * Constructs a InlineResponse20042 from a plain JavaScript object, optionally creating a new instance. + * Copies all relevant properties from data to obj if supplied or a new instance if not. + * @param {Object} data The plain JavaScript object bearing properties of interest. + * @param {module:model/InlineResponse20042} obj Optional instance to populate. + * @return {module:model/InlineResponse20042} The populated InlineResponse20042 instance. + */ + static constructFromObject(data, obj) { + if (data) { + obj = obj || new InlineResponse20042(); + + if (data.hasOwnProperty('ok')) { + obj['ok'] = ApiClient.convertToType(data['ok'], 'Boolean'); + } + if (data.hasOwnProperty('bookings')) { + obj['bookings'] = ApiClient.convertToType(data['bookings'], [Object]); + } + } + return obj; + } + + +} + +/** + * @member {Boolean} ok + */ +InlineResponse20042.prototype['ok'] = undefined; + +/** + * @member {Array.} bookings + */ +InlineResponse20042.prototype['bookings'] = undefined; + + + + + + +export default InlineResponse20042; + diff --git a/src/model/InlineResponse2005.js b/src/model/InlineResponse2005.js index 892bb895..bc95a641 100644 --- a/src/model/InlineResponse2005.js +++ b/src/model/InlineResponse2005.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -16,7 +16,7 @@ import ApiClient from '../ApiClient'; /** * The InlineResponse2005 model module. * @module model/InlineResponse2005 - * @version 1.0.3 + * @version 1.4.2 */ class InlineResponse2005 { /** diff --git a/src/model/InlineResponse2006.js b/src/model/InlineResponse2006.js index be565485..37dbec7d 100644 --- a/src/model/InlineResponse2006.js +++ b/src/model/InlineResponse2006.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -17,7 +17,7 @@ import Room from './Room'; /** * The InlineResponse2006 model module. * @module model/InlineResponse2006 - * @version 1.0.3 + * @version 1.4.2 */ class InlineResponse2006 { /** diff --git a/src/model/InlineResponse2007.js b/src/model/InlineResponse2007.js index 1c3613a4..23c4a8e4 100644 --- a/src/model/InlineResponse2007.js +++ b/src/model/InlineResponse2007.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -17,7 +17,7 @@ import Booking from './Booking'; /** * The InlineResponse2007 model module. * @module model/InlineResponse2007 - * @version 1.0.3 + * @version 1.4.2 */ class InlineResponse2007 { /** diff --git a/src/model/InlineResponse2008.js b/src/model/InlineResponse2008.js index 94f8d736..176cc120 100644 --- a/src/model/InlineResponse2008.js +++ b/src/model/InlineResponse2008.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -17,7 +17,7 @@ import Equipment from './Equipment'; /** * The InlineResponse2008 model module. * @module model/InlineResponse2008 - * @version 1.0.3 + * @version 1.4.2 */ class InlineResponse2008 { /** diff --git a/src/model/InlineResponse2009.js b/src/model/InlineResponse2009.js index ba362c50..3daea0f7 100644 --- a/src/model/InlineResponse2009.js +++ b/src/model/InlineResponse2009.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -17,7 +17,7 @@ import Room from './Room'; /** * The InlineResponse2009 model module. * @module model/InlineResponse2009 - * @version 1.0.3 + * @version 1.4.2 */ class InlineResponse2009 { /** diff --git a/src/model/Instance.js b/src/model/Instance.js index 42809d16..93b53216 100644 --- a/src/model/Instance.js +++ b/src/model/Instance.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -18,7 +18,7 @@ import Period from './Period'; /** * The Instance model module. * @module model/Instance - * @version 1.0.3 + * @version 1.4.2 */ class Instance { /** diff --git a/src/model/Lecturer.js b/src/model/Lecturer.js index 735804ac..82fff92e 100644 --- a/src/model/Lecturer.js +++ b/src/model/Lecturer.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -16,7 +16,7 @@ import ApiClient from '../ApiClient'; /** * The Lecturer model module. * @module model/Lecturer - * @version 1.0.3 + * @version 1.4.2 */ class Lecturer { /** diff --git a/src/model/LibcalBooking.js b/src/model/LibcalBooking.js new file mode 100644 index 00000000..1dd3619b --- /dev/null +++ b/src/model/LibcalBooking.js @@ -0,0 +1,108 @@ +/** + * UCL API + * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` + * + * The version of the OpenAPI document: 1.4.2 + * Contact: isd.apiteam@ucl.ac.uk + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + * + */ + +import ApiClient from '../ApiClient'; + +/** + * The LibcalBooking model module. + * @module model/LibcalBooking + * @version 1.4.2 + */ +class LibcalBooking { + /** + * Constructs a new LibcalBooking. + * @alias module:model/LibcalBooking + */ + constructor() { + + LibcalBooking.initialize(this); + } + + /** + * Initializes the fields of this object. + * This method is used by the constructors of any subclasses, in order to implement multiple inheritance (mix-ins). + * Only for internal use. + */ + static initialize(obj) { + } + + /** + * Constructs a LibcalBooking from a plain JavaScript object, optionally creating a new instance. + * Copies all relevant properties from data to obj if supplied or a new instance if not. + * @param {Object} data The plain JavaScript object bearing properties of interest. + * @param {module:model/LibcalBooking} obj Optional instance to populate. + * @return {module:model/LibcalBooking} The populated LibcalBooking instance. + */ + static constructFromObject(data, obj) { + if (data) { + obj = obj || new LibcalBooking(); + + if (data.hasOwnProperty('nickname')) { + obj['nickname'] = ApiClient.convertToType(data['nickname'], 'String'); + } + if (data.hasOwnProperty('start')) { + obj['start'] = ApiClient.convertToType(data['start'], 'String'); + } + if (data.hasOwnProperty('end')) { + obj['end'] = ApiClient.convertToType(data['end'], 'String'); + } + if (data.hasOwnProperty('created')) { + obj['created'] = ApiClient.convertToType(data['created'], 'String'); + } + if (data.hasOwnProperty('booking_id')) { + obj['booking_id'] = ApiClient.convertToType(data['booking_id'], 'String'); + } + } + return obj; + } + + +} + +/** + * Nickname assigned to this LibCal booking + * @member {String} nickname + */ +LibcalBooking.prototype['nickname'] = undefined; + +/** + * Timestamp (in ISO 8601 format) at which this LibCal booking starts + * @member {String} start + */ +LibcalBooking.prototype['start'] = undefined; + +/** + * Timestamp (in ISO 8601 format) at which this LibCal booking ends + * @member {String} end + */ +LibcalBooking.prototype['end'] = undefined; + +/** + * Timestamp (in ISO 8601 format) denoting when this LibCal booking was created + * @member {String} created + */ +LibcalBooking.prototype['created'] = undefined; + +/** + * ID assigned to this LibCal booking + * @member {String} booking_id + */ +LibcalBooking.prototype['booking_id'] = undefined; + + + + + + +export default LibcalBooking; + diff --git a/src/model/LibcalCategory.js b/src/model/LibcalCategory.js new file mode 100644 index 00000000..7bc532b2 --- /dev/null +++ b/src/model/LibcalCategory.js @@ -0,0 +1,99 @@ +/** + * UCL API + * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` + * + * The version of the OpenAPI document: 1.4.2 + * Contact: isd.apiteam@ucl.ac.uk + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + * + */ + +import ApiClient from '../ApiClient'; + +/** + * The LibcalCategory model module. + * @module model/LibcalCategory + * @version 1.4.2 + */ +class LibcalCategory { + /** + * Constructs a new LibcalCategory. + * @alias module:model/LibcalCategory + */ + constructor() { + + LibcalCategory.initialize(this); + } + + /** + * Initializes the fields of this object. + * This method is used by the constructors of any subclasses, in order to implement multiple inheritance (mix-ins). + * Only for internal use. + */ + static initialize(obj) { + } + + /** + * Constructs a LibcalCategory from a plain JavaScript object, optionally creating a new instance. + * Copies all relevant properties from data to obj if supplied or a new instance if not. + * @param {Object} data The plain JavaScript object bearing properties of interest. + * @param {module:model/LibcalCategory} obj Optional instance to populate. + * @return {module:model/LibcalCategory} The populated LibcalCategory instance. + */ + static constructFromObject(data, obj) { + if (data) { + obj = obj || new LibcalCategory(); + + if (data.hasOwnProperty('cid')) { + obj['cid'] = ApiClient.convertToType(data['cid'], 'Number'); + } + if (data.hasOwnProperty('formid')) { + obj['formid'] = ApiClient.convertToType(data['formid'], 'Number'); + } + if (data.hasOwnProperty('name')) { + obj['name'] = ApiClient.convertToType(data['name'], 'String'); + } + if (data.hasOwnProperty('public')) { + obj['public'] = ApiClient.convertToType(data['public'], 'Number'); + } + } + return obj; + } + + +} + +/** + * LibCal category ID denoting a category assigned to a particular space + * @member {Number} cid + */ +LibcalCategory.prototype['cid'] = undefined; + +/** + * LibCal booking form ID + * @member {Number} formid + */ +LibcalCategory.prototype['formid'] = undefined; + +/** + * Name of the category + * @member {String} name + */ +LibcalCategory.prototype['name'] = undefined; + +/** + * 1 if the category of spaces is publicly-bookable, 0 if it is not + * @member {Number} public + */ +LibcalCategory.prototype['public'] = undefined; + + + + + + +export default LibcalCategory; + diff --git a/src/model/LibcalForm.js b/src/model/LibcalForm.js new file mode 100644 index 00000000..ce68ffd5 --- /dev/null +++ b/src/model/LibcalForm.js @@ -0,0 +1,90 @@ +/** + * UCL API + * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` + * + * The version of the OpenAPI document: 1.4.2 + * Contact: isd.apiteam@ucl.ac.uk + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + * + */ + +import ApiClient from '../ApiClient'; +import LibcalFormField from './LibcalFormField'; + +/** + * The LibcalForm model module. + * @module model/LibcalForm + * @version 1.4.2 + */ +class LibcalForm { + /** + * Constructs a new LibcalForm. + * @alias module:model/LibcalForm + */ + constructor() { + + LibcalForm.initialize(this); + } + + /** + * Initializes the fields of this object. + * This method is used by the constructors of any subclasses, in order to implement multiple inheritance (mix-ins). + * Only for internal use. + */ + static initialize(obj) { + } + + /** + * Constructs a LibcalForm from a plain JavaScript object, optionally creating a new instance. + * Copies all relevant properties from data to obj if supplied or a new instance if not. + * @param {Object} data The plain JavaScript object bearing properties of interest. + * @param {module:model/LibcalForm} obj Optional instance to populate. + * @return {module:model/LibcalForm} The populated LibcalForm instance. + */ + static constructFromObject(data, obj) { + if (data) { + obj = obj || new LibcalForm(); + + if (data.hasOwnProperty('id')) { + obj['id'] = ApiClient.convertToType(data['id'], 'Number'); + } + if (data.hasOwnProperty('name')) { + obj['name'] = ApiClient.convertToType(data['name'], 'String'); + } + if (data.hasOwnProperty('fields')) { + obj['fields'] = ApiClient.convertToType(data['fields'], [LibcalFormField]); + } + } + return obj; + } + + +} + +/** + * LibCal booking form ID + * @member {Number} id + */ +LibcalForm.prototype['id'] = undefined; + +/** + * Name of the LibCal booking form + * @member {String} name + */ +LibcalForm.prototype['name'] = undefined; + +/** + * @member {Array.} fields + */ +LibcalForm.prototype['fields'] = undefined; + + + + + + +export default LibcalForm; + diff --git a/src/model/LibcalFormField.js b/src/model/LibcalFormField.js new file mode 100644 index 00000000..1f56f7de --- /dev/null +++ b/src/model/LibcalFormField.js @@ -0,0 +1,99 @@ +/** + * UCL API + * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` + * + * The version of the OpenAPI document: 1.4.2 + * Contact: isd.apiteam@ucl.ac.uk + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + * + */ + +import ApiClient from '../ApiClient'; + +/** + * The LibcalFormField model module. + * @module model/LibcalFormField + * @version 1.4.2 + */ +class LibcalFormField { + /** + * Constructs a new LibcalFormField. + * @alias module:model/LibcalFormField + */ + constructor() { + + LibcalFormField.initialize(this); + } + + /** + * Initializes the fields of this object. + * This method is used by the constructors of any subclasses, in order to implement multiple inheritance (mix-ins). + * Only for internal use. + */ + static initialize(obj) { + } + + /** + * Constructs a LibcalFormField from a plain JavaScript object, optionally creating a new instance. + * Copies all relevant properties from data to obj if supplied or a new instance if not. + * @param {Object} data The plain JavaScript object bearing properties of interest. + * @param {module:model/LibcalFormField} obj Optional instance to populate. + * @return {module:model/LibcalFormField} The populated LibcalFormField instance. + */ + static constructFromObject(data, obj) { + if (data) { + obj = obj || new LibcalFormField(); + + if (data.hasOwnProperty('label')) { + obj['label'] = ApiClient.convertToType(data['label'], 'String'); + } + if (data.hasOwnProperty('type')) { + obj['type'] = ApiClient.convertToType(data['type'], 'String'); + } + if (data.hasOwnProperty('required')) { + obj['required'] = ApiClient.convertToType(data['required'], 'Boolean'); + } + if (data.hasOwnProperty('options')) { + obj['options'] = ApiClient.convertToType(data['options'], ['String']); + } + } + return obj; + } + + +} + +/** + * Label for the field in the LibCal booking form + * @member {String} label + */ +LibcalFormField.prototype['label'] = undefined; + +/** + * Field type for the field in the LibCal booking form. Examples of field types include 'string' and 'dropdown'. + * @member {String} type + */ +LibcalFormField.prototype['type'] = undefined; + +/** + * Whether the field in the LibCal booking form is required (true) or optional (false) + * @member {Boolean} required + */ +LibcalFormField.prototype['required'] = undefined; + +/** + * Array of options that will be provided if the field type is dropdown + * @member {Array.} options + */ +LibcalFormField.prototype['options'] = undefined; + + + + + + +export default LibcalFormField; + diff --git a/src/model/LibcalLocation.js b/src/model/LibcalLocation.js new file mode 100644 index 00000000..c3a4acbe --- /dev/null +++ b/src/model/LibcalLocation.js @@ -0,0 +1,113 @@ +/** + * UCL API + * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` + * + * The version of the OpenAPI document: 1.4.2 + * Contact: isd.apiteam@ucl.ac.uk + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + * + */ + +import ApiClient from '../ApiClient'; +import LibcalLocationBase from './LibcalLocationBase'; + +/** + * The LibcalLocation model module. + * @module model/LibcalLocation + * @version 1.4.2 + */ +class LibcalLocation { + /** + * Constructs a new LibcalLocation. + * @alias module:model/LibcalLocation + * @implements module:model/LibcalLocationBase + */ + constructor() { + LibcalLocationBase.initialize(this); + LibcalLocation.initialize(this); + } + + /** + * Initializes the fields of this object. + * This method is used by the constructors of any subclasses, in order to implement multiple inheritance (mix-ins). + * Only for internal use. + */ + static initialize(obj) { + } + + /** + * Constructs a LibcalLocation from a plain JavaScript object, optionally creating a new instance. + * Copies all relevant properties from data to obj if supplied or a new instance if not. + * @param {Object} data The plain JavaScript object bearing properties of interest. + * @param {module:model/LibcalLocation} obj Optional instance to populate. + * @return {module:model/LibcalLocation} The populated LibcalLocation instance. + */ + static constructFromObject(data, obj) { + if (data) { + obj = obj || new LibcalLocation(); + LibcalLocationBase.constructFromObject(data, obj); + + if (data.hasOwnProperty('public')) { + obj['public'] = ApiClient.convertToType(data['public'], 'Number'); + } + if (data.hasOwnProperty('terms')) { + obj['terms'] = ApiClient.convertToType(data['terms'], 'String'); + } + if (data.hasOwnProperty('lid')) { + obj['lid'] = ApiClient.convertToType(data['lid'], 'Number'); + } + if (data.hasOwnProperty('name')) { + obj['name'] = ApiClient.convertToType(data['name'], 'String'); + } + } + return obj; + } + + +} + +/** + * 1 if the location is publicly-bookable, 0 if it is not + * @member {Number} public + */ +LibcalLocation.prototype['public'] = undefined; + +/** + * Additional details about the location, such as terms & conditions. May include HTML. + * @member {String} terms + */ +LibcalLocation.prototype['terms'] = undefined; + +/** + * ID for the LibCal location in question + * @member {Number} lid + */ +LibcalLocation.prototype['lid'] = undefined; + +/** + * Name of the LibCal location in question + * @member {String} name + */ +LibcalLocation.prototype['name'] = undefined; + + +// Implement LibcalLocationBase interface: +/** + * ID for the LibCal location in question + * @member {Number} lid + */ +LibcalLocationBase.prototype['lid'] = undefined; +/** + * Name of the LibCal location in question + * @member {String} name + */ +LibcalLocationBase.prototype['name'] = undefined; + + + + +export default LibcalLocation; + diff --git a/src/model/LibcalLocationBase.js b/src/model/LibcalLocationBase.js new file mode 100644 index 00000000..bbb0f224 --- /dev/null +++ b/src/model/LibcalLocationBase.js @@ -0,0 +1,81 @@ +/** + * UCL API + * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` + * + * The version of the OpenAPI document: 1.4.2 + * Contact: isd.apiteam@ucl.ac.uk + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + * + */ + +import ApiClient from '../ApiClient'; + +/** + * The LibcalLocationBase model module. + * @module model/LibcalLocationBase + * @version 1.4.2 + */ +class LibcalLocationBase { + /** + * Constructs a new LibcalLocationBase. + * @alias module:model/LibcalLocationBase + */ + constructor() { + + LibcalLocationBase.initialize(this); + } + + /** + * Initializes the fields of this object. + * This method is used by the constructors of any subclasses, in order to implement multiple inheritance (mix-ins). + * Only for internal use. + */ + static initialize(obj) { + } + + /** + * Constructs a LibcalLocationBase from a plain JavaScript object, optionally creating a new instance. + * Copies all relevant properties from data to obj if supplied or a new instance if not. + * @param {Object} data The plain JavaScript object bearing properties of interest. + * @param {module:model/LibcalLocationBase} obj Optional instance to populate. + * @return {module:model/LibcalLocationBase} The populated LibcalLocationBase instance. + */ + static constructFromObject(data, obj) { + if (data) { + obj = obj || new LibcalLocationBase(); + + if (data.hasOwnProperty('lid')) { + obj['lid'] = ApiClient.convertToType(data['lid'], 'Number'); + } + if (data.hasOwnProperty('name')) { + obj['name'] = ApiClient.convertToType(data['name'], 'String'); + } + } + return obj; + } + + +} + +/** + * ID for the LibCal location in question + * @member {Number} lid + */ +LibcalLocationBase.prototype['lid'] = undefined; + +/** + * Name of the LibCal location in question + * @member {String} name + */ +LibcalLocationBase.prototype['name'] = undefined; + + + + + + +export default LibcalLocationBase; + diff --git a/src/model/LibcalPersonalSeatBooking.js b/src/model/LibcalPersonalSeatBooking.js new file mode 100644 index 00000000..268ec1bb --- /dev/null +++ b/src/model/LibcalPersonalSeatBooking.js @@ -0,0 +1,294 @@ +/** + * UCL API + * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` + * + * The version of the OpenAPI document: 1.4.2 + * Contact: isd.apiteam@ucl.ac.uk + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + * + */ + +import ApiClient from '../ApiClient'; +import LibcalSeatBooking from './LibcalSeatBooking'; + +/** + * The LibcalPersonalSeatBooking model module. + * @module model/LibcalPersonalSeatBooking + * @version 1.4.2 + */ +class LibcalPersonalSeatBooking { + /** + * Constructs a new LibcalPersonalSeatBooking. + * @alias module:model/LibcalPersonalSeatBooking + * @implements module:model/LibcalSeatBooking + */ + constructor() { + LibcalSeatBooking.initialize(this); + LibcalPersonalSeatBooking.initialize(this); + } + + /** + * Initializes the fields of this object. + * This method is used by the constructors of any subclasses, in order to implement multiple inheritance (mix-ins). + * Only for internal use. + */ + static initialize(obj) { + } + + /** + * Constructs a LibcalPersonalSeatBooking from a plain JavaScript object, optionally creating a new instance. + * Copies all relevant properties from data to obj if supplied or a new instance if not. + * @param {Object} data The plain JavaScript object bearing properties of interest. + * @param {module:model/LibcalPersonalSeatBooking} obj Optional instance to populate. + * @return {module:model/LibcalPersonalSeatBooking} The populated LibcalPersonalSeatBooking instance. + */ + static constructFromObject(data, obj) { + if (data) { + obj = obj || new LibcalPersonalSeatBooking(); + LibcalSeatBooking.constructFromObject(data, obj); + + if (data.hasOwnProperty('book_id')) { + obj['book_id'] = ApiClient.convertToType(data['book_id'], 'String'); + } + if (data.hasOwnProperty('first_name')) { + obj['first_name'] = ApiClient.convertToType(data['first_name'], 'String'); + } + if (data.hasOwnProperty('last_name')) { + obj['last_name'] = ApiClient.convertToType(data['last_name'], 'String'); + } + if (data.hasOwnProperty('email')) { + obj['email'] = ApiClient.convertToType(data['email'], 'String'); + } + if (data.hasOwnProperty('check_in_code')) { + obj['check_in_code'] = ApiClient.convertToType(data['check_in_code'], 'String'); + } + if (data.hasOwnProperty('eid')) { + obj['eid'] = ApiClient.convertToType(data['eid'], 'Number'); + } + if (data.hasOwnProperty('cid')) { + obj['cid'] = ApiClient.convertToType(data['cid'], 'Number'); + } + if (data.hasOwnProperty('lid')) { + obj['lid'] = ApiClient.convertToType(data['lid'], 'Number'); + } + if (data.hasOwnProperty('from_date')) { + obj['from_date'] = ApiClient.convertToType(data['from_date'], 'String'); + } + if (data.hasOwnProperty('to_date')) { + obj['to_date'] = ApiClient.convertToType(data['to_date'], 'String'); + } + if (data.hasOwnProperty('created')) { + obj['created'] = ApiClient.convertToType(data['created'], 'String'); + } + if (data.hasOwnProperty('status')) { + obj['status'] = ApiClient.convertToType(data['status'], 'String'); + } + if (data.hasOwnProperty('location_name')) { + obj['location_name'] = ApiClient.convertToType(data['location_name'], 'String'); + } + if (data.hasOwnProperty('category_name')) { + obj['category_name'] = ApiClient.convertToType(data['category_name'], 'String'); + } + if (data.hasOwnProperty('item_name')) { + obj['item_name'] = ApiClient.convertToType(data['item_name'], 'String'); + } + if (data.hasOwnProperty('seat_id')) { + obj['seat_id'] = ApiClient.convertToType(data['seat_id'], 'Number'); + } + if (data.hasOwnProperty('seat_name')) { + obj['seat_name'] = ApiClient.convertToType(data['seat_name'], 'String'); + } + if (data.hasOwnProperty('cancelled')) { + obj['cancelled'] = ApiClient.convertToType(data['cancelled'], 'String'); + } + } + return obj; + } + + +} + +/** + * ID assigned to this LibCal booking + * @member {String} book_id + */ +LibcalPersonalSeatBooking.prototype['book_id'] = undefined; + +/** + * First name of the user who booked this + * @member {String} first_name + */ +LibcalPersonalSeatBooking.prototype['first_name'] = undefined; + +/** + * Last name of the user who booked this + * @member {String} last_name + */ +LibcalPersonalSeatBooking.prototype['last_name'] = undefined; + +/** + * Email address of the user who booked this + * @member {String} email + */ +LibcalPersonalSeatBooking.prototype['email'] = undefined; + +/** + * Email address of the user who booked this + * @member {String} check_in_code + */ +LibcalPersonalSeatBooking.prototype['check_in_code'] = undefined; + +/** + * ID of this LibCal space + * @member {Number} eid + */ +LibcalPersonalSeatBooking.prototype['eid'] = undefined; + +/** + * LibCal category ID denoting a category assigned to a particular space + * @member {Number} cid + */ +LibcalPersonalSeatBooking.prototype['cid'] = undefined; + +/** + * LibCal Location ID + * @member {Number} lid + */ +LibcalPersonalSeatBooking.prototype['lid'] = undefined; + +/** + * Timestamp (in ISO 8601 format) at which this LibCal booking starts + * @member {String} from_date + */ +LibcalPersonalSeatBooking.prototype['from_date'] = undefined; + +/** + * Timestamp (in ISO 8601 format) at which this LibCal booking ends + * @member {String} to_date + */ +LibcalPersonalSeatBooking.prototype['to_date'] = undefined; + +/** + * Timestamp (in ISO 8601 format) denoting when this LibCal booking was created + * @member {String} created + */ +LibcalPersonalSeatBooking.prototype['created'] = undefined; + +/** + * Status of this LibCal booking + * @member {String} status + */ +LibcalPersonalSeatBooking.prototype['status'] = undefined; + +/** + * Name of the LibCal location in question + * @member {String} location_name + */ +LibcalPersonalSeatBooking.prototype['location_name'] = undefined; + +/** + * Name of the category + * @member {String} category_name + */ +LibcalPersonalSeatBooking.prototype['category_name'] = undefined; + +/** + * Name of this LibCal space + * @member {String} item_name + */ +LibcalPersonalSeatBooking.prototype['item_name'] = undefined; + +/** + * LibCal seat ID + * @member {Number} seat_id + */ +LibcalPersonalSeatBooking.prototype['seat_id'] = undefined; + +/** + * Name of the LibCal seat + * @member {String} seat_name + */ +LibcalPersonalSeatBooking.prototype['seat_name'] = undefined; + +/** + * Timestamp (in ISO 8601 format) at which this LibCal booking was cancelled, if applicable + * @member {String} cancelled + */ +LibcalPersonalSeatBooking.prototype['cancelled'] = undefined; + + +// Implement LibcalSeatBooking interface: +/** + * ID of this LibCal space + * @member {Number} eid + */ +LibcalSeatBooking.prototype['eid'] = undefined; +/** + * LibCal category ID denoting a category assigned to a particular space + * @member {Number} cid + */ +LibcalSeatBooking.prototype['cid'] = undefined; +/** + * LibCal Location ID + * @member {Number} lid + */ +LibcalSeatBooking.prototype['lid'] = undefined; +/** + * Timestamp (in ISO 8601 format) at which this LibCal booking starts + * @member {String} from_date + */ +LibcalSeatBooking.prototype['from_date'] = undefined; +/** + * Timestamp (in ISO 8601 format) at which this LibCal booking ends + * @member {String} to_date + */ +LibcalSeatBooking.prototype['to_date'] = undefined; +/** + * Timestamp (in ISO 8601 format) denoting when this LibCal booking was created + * @member {String} created + */ +LibcalSeatBooking.prototype['created'] = undefined; +/** + * Status of this LibCal booking + * @member {String} status + */ +LibcalSeatBooking.prototype['status'] = undefined; +/** + * Name of the LibCal location in question + * @member {String} location_name + */ +LibcalSeatBooking.prototype['location_name'] = undefined; +/** + * Name of the category + * @member {String} category_name + */ +LibcalSeatBooking.prototype['category_name'] = undefined; +/** + * Name of this LibCal space + * @member {String} item_name + */ +LibcalSeatBooking.prototype['item_name'] = undefined; +/** + * LibCal seat ID + * @member {Number} seat_id + */ +LibcalSeatBooking.prototype['seat_id'] = undefined; +/** + * Name of the LibCal seat + * @member {String} seat_name + */ +LibcalSeatBooking.prototype['seat_name'] = undefined; +/** + * Timestamp (in ISO 8601 format) at which this LibCal booking was cancelled, if applicable + * @member {String} cancelled + */ +LibcalSeatBooking.prototype['cancelled'] = undefined; + + + + +export default LibcalPersonalSeatBooking; + diff --git a/src/model/LibcalReserveRequest.js b/src/model/LibcalReserveRequest.js new file mode 100644 index 00000000..2f910cce --- /dev/null +++ b/src/model/LibcalReserveRequest.js @@ -0,0 +1,103 @@ +/** + * UCL API + * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` + * + * The version of the OpenAPI document: 1.4.2 + * Contact: isd.apiteam@ucl.ac.uk + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + * + */ + +import ApiClient from '../ApiClient'; +import LibcalReserveRequestBooking from './LibcalReserveRequestBooking'; + +/** + * The LibcalReserveRequest model module. + * @module model/LibcalReserveRequest + * @version 1.4.2 + */ +class LibcalReserveRequest { + /** + * Constructs a new LibcalReserveRequest. + * @alias module:model/LibcalReserveRequest + * @param start {String} Timestamp (in ISO 8601 format) at which this LibCal booking starts + * @param test {Number} Whether or not this is a test booking. If set, the system will process the booking but will not actually make it. This is useful during development. + */ + constructor(start, test) { + + LibcalReserveRequest.initialize(this, start, test); + } + + /** + * Initializes the fields of this object. + * This method is used by the constructors of any subclasses, in order to implement multiple inheritance (mix-ins). + * Only for internal use. + */ + static initialize(obj, start, test) { + obj['start'] = start; + obj['test'] = test; + } + + /** + * Constructs a LibcalReserveRequest from a plain JavaScript object, optionally creating a new instance. + * Copies all relevant properties from data to obj if supplied or a new instance if not. + * @param {Object} data The plain JavaScript object bearing properties of interest. + * @param {module:model/LibcalReserveRequest} obj Optional instance to populate. + * @return {module:model/LibcalReserveRequest} The populated LibcalReserveRequest instance. + */ + static constructFromObject(data, obj) { + if (data) { + obj = obj || new LibcalReserveRequest(); + + if (data.hasOwnProperty('start')) { + obj['start'] = ApiClient.convertToType(data['start'], 'String'); + } + if (data.hasOwnProperty('test')) { + obj['test'] = ApiClient.convertToType(data['test'], 'Number'); + } + if (data.hasOwnProperty('nickname')) { + obj['nickname'] = ApiClient.convertToType(data['nickname'], 'String'); + } + if (data.hasOwnProperty('bookings')) { + obj['bookings'] = ApiClient.convertToType(data['bookings'], [LibcalReserveRequestBooking]); + } + } + return obj; + } + + +} + +/** + * Timestamp (in ISO 8601 format) at which this LibCal booking starts + * @member {String} start + */ +LibcalReserveRequest.prototype['start'] = undefined; + +/** + * Whether or not this is a test booking. If set, the system will process the booking but will not actually make it. This is useful during development. + * @member {Number} test + */ +LibcalReserveRequest.prototype['test'] = undefined; + +/** + * If the space to be booked has a nickname, then the nickname must be supplied here. + * @member {String} nickname + */ +LibcalReserveRequest.prototype['nickname'] = undefined; + +/** + * @member {Array.} bookings + */ +LibcalReserveRequest.prototype['bookings'] = undefined; + + + + + + +export default LibcalReserveRequest; + diff --git a/src/model/LibcalReserveRequestBooking.js b/src/model/LibcalReserveRequestBooking.js new file mode 100644 index 00000000..8d2ec055 --- /dev/null +++ b/src/model/LibcalReserveRequestBooking.js @@ -0,0 +1,95 @@ +/** + * UCL API + * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` + * + * The version of the OpenAPI document: 1.4.2 + * Contact: isd.apiteam@ucl.ac.uk + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + * + */ + +import ApiClient from '../ApiClient'; + +/** + * The LibcalReserveRequestBooking model module. + * @module model/LibcalReserveRequestBooking + * @version 1.4.2 + */ +class LibcalReserveRequestBooking { + /** + * Constructs a new LibcalReserveRequestBooking. + * Specify seat_id if booking a seat, otherwise omit it + * @alias module:model/LibcalReserveRequestBooking + * @param id {Number} ID of this LibCal space + * @param to {String} Timestamp (in ISO 8601 format) at which this LibCal booking ends + */ + constructor(id, to) { + + LibcalReserveRequestBooking.initialize(this, id, to); + } + + /** + * Initializes the fields of this object. + * This method is used by the constructors of any subclasses, in order to implement multiple inheritance (mix-ins). + * Only for internal use. + */ + static initialize(obj, id, to) { + obj['id'] = id; + obj['to'] = to; + } + + /** + * Constructs a LibcalReserveRequestBooking from a plain JavaScript object, optionally creating a new instance. + * Copies all relevant properties from data to obj if supplied or a new instance if not. + * @param {Object} data The plain JavaScript object bearing properties of interest. + * @param {module:model/LibcalReserveRequestBooking} obj Optional instance to populate. + * @return {module:model/LibcalReserveRequestBooking} The populated LibcalReserveRequestBooking instance. + */ + static constructFromObject(data, obj) { + if (data) { + obj = obj || new LibcalReserveRequestBooking(); + + if (data.hasOwnProperty('id')) { + obj['id'] = ApiClient.convertToType(data['id'], 'Number'); + } + if (data.hasOwnProperty('to')) { + obj['to'] = ApiClient.convertToType(data['to'], 'String'); + } + if (data.hasOwnProperty('seat_id')) { + obj['seat_id'] = ApiClient.convertToType(data['seat_id'], 'Number'); + } + } + return obj; + } + + +} + +/** + * ID of this LibCal space + * @member {Number} id + */ +LibcalReserveRequestBooking.prototype['id'] = undefined; + +/** + * Timestamp (in ISO 8601 format) at which this LibCal booking ends + * @member {String} to + */ +LibcalReserveRequestBooking.prototype['to'] = undefined; + +/** + * LibCal seat ID + * @member {Number} seat_id + */ +LibcalReserveRequestBooking.prototype['seat_id'] = undefined; + + + + + + +export default LibcalReserveRequestBooking; + diff --git a/src/model/LibcalSeat.js b/src/model/LibcalSeat.js new file mode 100644 index 00000000..2c5bf653 --- /dev/null +++ b/src/model/LibcalSeat.js @@ -0,0 +1,126 @@ +/** + * UCL API + * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` + * + * The version of the OpenAPI document: 1.4.2 + * Contact: isd.apiteam@ucl.ac.uk + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + * + */ + +import ApiClient from '../ApiClient'; + +/** + * The LibcalSeat model module. + * @module model/LibcalSeat + * @version 1.4.2 + */ +class LibcalSeat { + /** + * Constructs a new LibcalSeat. + * @alias module:model/LibcalSeat + */ + constructor() { + + LibcalSeat.initialize(this); + } + + /** + * Initializes the fields of this object. + * This method is used by the constructors of any subclasses, in order to implement multiple inheritance (mix-ins). + * Only for internal use. + */ + static initialize(obj) { + } + + /** + * Constructs a LibcalSeat from a plain JavaScript object, optionally creating a new instance. + * Copies all relevant properties from data to obj if supplied or a new instance if not. + * @param {Object} data The plain JavaScript object bearing properties of interest. + * @param {module:model/LibcalSeat} obj Optional instance to populate. + * @return {module:model/LibcalSeat} The populated LibcalSeat instance. + */ + static constructFromObject(data, obj) { + if (data) { + obj = obj || new LibcalSeat(); + + if (data.hasOwnProperty('id')) { + obj['id'] = ApiClient.convertToType(data['id'], 'Number'); + } + if (data.hasOwnProperty('name')) { + obj['name'] = ApiClient.convertToType(data['name'], 'String'); + } + if (data.hasOwnProperty('description')) { + obj['description'] = ApiClient.convertToType(data['description'], 'String'); + } + if (data.hasOwnProperty('is_accessible')) { + obj['is_accessible'] = ApiClient.convertToType(data['is_accessible'], 'Boolean'); + } + if (data.hasOwnProperty('is_powered')) { + obj['is_powered'] = ApiClient.convertToType(data['is_powered'], 'Boolean'); + } + if (data.hasOwnProperty('image')) { + obj['image'] = ApiClient.convertToType(data['image'], 'String'); + } + if (data.hasOwnProperty('status')) { + obj['status'] = ApiClient.convertToType(data['status'], 'Boolean'); + } + } + return obj; + } + + +} + +/** + * LibCal seat ID + * @member {Number} id + */ +LibcalSeat.prototype['id'] = undefined; + +/** + * Name of the LibCal seat + * @member {String} name + */ +LibcalSeat.prototype['name'] = undefined; + +/** + * Description provided for the LibCal seat. May contain HTML + * @member {String} description + */ +LibcalSeat.prototype['description'] = undefined; + +/** + * Whether the seat is height-adjustable and hence accessible by the differently-abled + * @member {Boolean} is_accessible + */ +LibcalSeat.prototype['is_accessible'] = undefined; + +/** + * Whether a power socket is available at the seat + * @member {Boolean} is_powered + */ +LibcalSeat.prototype['is_powered'] = undefined; + +/** + * A URL pointing to an image of the seat. If none is available, an empty string will be returned + * @member {String} image + */ +LibcalSeat.prototype['image'] = undefined; + +/** + * The current status of the seat + * @member {Boolean} status + */ +LibcalSeat.prototype['status'] = undefined; + + + + + + +export default LibcalSeat; + diff --git a/src/model/LibcalSeatBooking.js b/src/model/LibcalSeatBooking.js new file mode 100644 index 00000000..6d451b63 --- /dev/null +++ b/src/model/LibcalSeatBooking.js @@ -0,0 +1,180 @@ +/** + * UCL API + * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` + * + * The version of the OpenAPI document: 1.4.2 + * Contact: isd.apiteam@ucl.ac.uk + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + * + */ + +import ApiClient from '../ApiClient'; + +/** + * The LibcalSeatBooking model module. + * @module model/LibcalSeatBooking + * @version 1.4.2 + */ +class LibcalSeatBooking { + /** + * Constructs a new LibcalSeatBooking. + * @alias module:model/LibcalSeatBooking + */ + constructor() { + + LibcalSeatBooking.initialize(this); + } + + /** + * Initializes the fields of this object. + * This method is used by the constructors of any subclasses, in order to implement multiple inheritance (mix-ins). + * Only for internal use. + */ + static initialize(obj) { + } + + /** + * Constructs a LibcalSeatBooking from a plain JavaScript object, optionally creating a new instance. + * Copies all relevant properties from data to obj if supplied or a new instance if not. + * @param {Object} data The plain JavaScript object bearing properties of interest. + * @param {module:model/LibcalSeatBooking} obj Optional instance to populate. + * @return {module:model/LibcalSeatBooking} The populated LibcalSeatBooking instance. + */ + static constructFromObject(data, obj) { + if (data) { + obj = obj || new LibcalSeatBooking(); + + if (data.hasOwnProperty('eid')) { + obj['eid'] = ApiClient.convertToType(data['eid'], 'Number'); + } + if (data.hasOwnProperty('cid')) { + obj['cid'] = ApiClient.convertToType(data['cid'], 'Number'); + } + if (data.hasOwnProperty('lid')) { + obj['lid'] = ApiClient.convertToType(data['lid'], 'Number'); + } + if (data.hasOwnProperty('from_date')) { + obj['from_date'] = ApiClient.convertToType(data['from_date'], 'String'); + } + if (data.hasOwnProperty('to_date')) { + obj['to_date'] = ApiClient.convertToType(data['to_date'], 'String'); + } + if (data.hasOwnProperty('created')) { + obj['created'] = ApiClient.convertToType(data['created'], 'String'); + } + if (data.hasOwnProperty('status')) { + obj['status'] = ApiClient.convertToType(data['status'], 'String'); + } + if (data.hasOwnProperty('location_name')) { + obj['location_name'] = ApiClient.convertToType(data['location_name'], 'String'); + } + if (data.hasOwnProperty('category_name')) { + obj['category_name'] = ApiClient.convertToType(data['category_name'], 'String'); + } + if (data.hasOwnProperty('item_name')) { + obj['item_name'] = ApiClient.convertToType(data['item_name'], 'String'); + } + if (data.hasOwnProperty('seat_id')) { + obj['seat_id'] = ApiClient.convertToType(data['seat_id'], 'Number'); + } + if (data.hasOwnProperty('seat_name')) { + obj['seat_name'] = ApiClient.convertToType(data['seat_name'], 'String'); + } + if (data.hasOwnProperty('cancelled')) { + obj['cancelled'] = ApiClient.convertToType(data['cancelled'], 'String'); + } + } + return obj; + } + + +} + +/** + * ID of this LibCal space + * @member {Number} eid + */ +LibcalSeatBooking.prototype['eid'] = undefined; + +/** + * LibCal category ID denoting a category assigned to a particular space + * @member {Number} cid + */ +LibcalSeatBooking.prototype['cid'] = undefined; + +/** + * LibCal Location ID + * @member {Number} lid + */ +LibcalSeatBooking.prototype['lid'] = undefined; + +/** + * Timestamp (in ISO 8601 format) at which this LibCal booking starts + * @member {String} from_date + */ +LibcalSeatBooking.prototype['from_date'] = undefined; + +/** + * Timestamp (in ISO 8601 format) at which this LibCal booking ends + * @member {String} to_date + */ +LibcalSeatBooking.prototype['to_date'] = undefined; + +/** + * Timestamp (in ISO 8601 format) denoting when this LibCal booking was created + * @member {String} created + */ +LibcalSeatBooking.prototype['created'] = undefined; + +/** + * Status of this LibCal booking + * @member {String} status + */ +LibcalSeatBooking.prototype['status'] = undefined; + +/** + * Name of the LibCal location in question + * @member {String} location_name + */ +LibcalSeatBooking.prototype['location_name'] = undefined; + +/** + * Name of the category + * @member {String} category_name + */ +LibcalSeatBooking.prototype['category_name'] = undefined; + +/** + * Name of this LibCal space + * @member {String} item_name + */ +LibcalSeatBooking.prototype['item_name'] = undefined; + +/** + * LibCal seat ID + * @member {Number} seat_id + */ +LibcalSeatBooking.prototype['seat_id'] = undefined; + +/** + * Name of the LibCal seat + * @member {String} seat_name + */ +LibcalSeatBooking.prototype['seat_name'] = undefined; + +/** + * Timestamp (in ISO 8601 format) at which this LibCal booking was cancelled, if applicable + * @member {String} cancelled + */ +LibcalSeatBooking.prototype['cancelled'] = undefined; + + + + + + +export default LibcalSeatBooking; + diff --git a/src/model/LibcalSpaceBase.js b/src/model/LibcalSpaceBase.js new file mode 100644 index 00000000..faf5a6f2 --- /dev/null +++ b/src/model/LibcalSpaceBase.js @@ -0,0 +1,117 @@ +/** + * UCL API + * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` + * + * The version of the OpenAPI document: 1.4.2 + * Contact: isd.apiteam@ucl.ac.uk + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + * + */ + +import ApiClient from '../ApiClient'; + +/** + * The LibcalSpaceBase model module. + * @module model/LibcalSpaceBase + * @version 1.4.2 + */ +class LibcalSpaceBase { + /** + * Constructs a new LibcalSpaceBase. + * @alias module:model/LibcalSpaceBase + */ + constructor() { + + LibcalSpaceBase.initialize(this); + } + + /** + * Initializes the fields of this object. + * This method is used by the constructors of any subclasses, in order to implement multiple inheritance (mix-ins). + * Only for internal use. + */ + static initialize(obj) { + } + + /** + * Constructs a LibcalSpaceBase from a plain JavaScript object, optionally creating a new instance. + * Copies all relevant properties from data to obj if supplied or a new instance if not. + * @param {Object} data The plain JavaScript object bearing properties of interest. + * @param {module:model/LibcalSpaceBase} obj Optional instance to populate. + * @return {module:model/LibcalSpaceBase} The populated LibcalSpaceBase instance. + */ + static constructFromObject(data, obj) { + if (data) { + obj = obj || new LibcalSpaceBase(); + + if (data.hasOwnProperty('id')) { + obj['id'] = ApiClient.convertToType(data['id'], 'Number'); + } + if (data.hasOwnProperty('name')) { + obj['name'] = ApiClient.convertToType(data['name'], 'String'); + } + if (data.hasOwnProperty('description')) { + obj['description'] = ApiClient.convertToType(data['description'], 'String'); + } + if (data.hasOwnProperty('image')) { + obj['image'] = ApiClient.convertToType(data['image'], 'String'); + } + if (data.hasOwnProperty('capacity')) { + obj['capacity'] = ApiClient.convertToType(data['capacity'], 'Number'); + } + if (data.hasOwnProperty('formid')) { + obj['formid'] = ApiClient.convertToType(data['formid'], 'Number'); + } + } + return obj; + } + + +} + +/** + * ID of this LibCal space + * @member {Number} id + */ +LibcalSpaceBase.prototype['id'] = undefined; + +/** + * Name of this LibCal space + * @member {String} name + */ +LibcalSpaceBase.prototype['name'] = undefined; + +/** + * Description of this LibCal space + * @member {String} description + */ +LibcalSpaceBase.prototype['description'] = undefined; + +/** + * URL pointing to an image depicting this LibCal space + * @member {String} image + */ +LibcalSpaceBase.prototype['image'] = undefined; + +/** + * Maximum number of persons this LibCal space can accommodate + * @member {Number} capacity + */ +LibcalSpaceBase.prototype['capacity'] = undefined; + +/** + * ID of the form associated with this LibCal space + * @member {Number} formid + */ +LibcalSpaceBase.prototype['formid'] = undefined; + + + + + + +export default LibcalSpaceBase; + diff --git a/src/model/LibcalUtilisationSeatSummary.js b/src/model/LibcalUtilisationSeatSummary.js new file mode 100644 index 00000000..b0df8860 --- /dev/null +++ b/src/model/LibcalUtilisationSeatSummary.js @@ -0,0 +1,90 @@ +/** + * UCL API + * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` + * + * The version of the OpenAPI document: 1.4.2 + * Contact: isd.apiteam@ucl.ac.uk + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + * + */ + +import ApiClient from '../ApiClient'; + +/** + * The LibcalUtilisationSeatSummary model module. + * @module model/LibcalUtilisationSeatSummary + * @version 1.4.2 + */ +class LibcalUtilisationSeatSummary { + /** + * Constructs a new LibcalUtilisationSeatSummary. + * @alias module:model/LibcalUtilisationSeatSummary + */ + constructor() { + + LibcalUtilisationSeatSummary.initialize(this); + } + + /** + * Initializes the fields of this object. + * This method is used by the constructors of any subclasses, in order to implement multiple inheritance (mix-ins). + * Only for internal use. + */ + static initialize(obj) { + } + + /** + * Constructs a LibcalUtilisationSeatSummary from a plain JavaScript object, optionally creating a new instance. + * Copies all relevant properties from data to obj if supplied or a new instance if not. + * @param {Object} data The plain JavaScript object bearing properties of interest. + * @param {module:model/LibcalUtilisationSeatSummary} obj Optional instance to populate. + * @return {module:model/LibcalUtilisationSeatSummary} The populated LibcalUtilisationSeatSummary instance. + */ + static constructFromObject(data, obj) { + if (data) { + obj = obj || new LibcalUtilisationSeatSummary(); + + if (data.hasOwnProperty('active')) { + obj['active'] = ApiClient.convertToType(data['active'], 'Number'); + } + if (data.hasOwnProperty('bookable_count')) { + obj['bookable_count'] = ApiClient.convertToType(data['bookable_count'], 'Number'); + } + if (data.hasOwnProperty('total')) { + obj['total'] = ApiClient.convertToType(data['total'], 'Number'); + } + } + return obj; + } + + +} + +/** + * Number of active LibCal bookings of seats + * @member {Number} active + */ +LibcalUtilisationSeatSummary.prototype['active'] = undefined; + +/** + * Number of LibCal seats available to be booked + * @member {Number} bookable_count + */ +LibcalUtilisationSeatSummary.prototype['bookable_count'] = undefined; + +/** + * Total number of LibCal seats in the location + * @member {Number} total + */ +LibcalUtilisationSeatSummary.prototype['total'] = undefined; + + + + + + +export default LibcalUtilisationSeatSummary; + diff --git a/src/model/LibcalUtilisationSpaceSummary.js b/src/model/LibcalUtilisationSpaceSummary.js new file mode 100644 index 00000000..88af0afd --- /dev/null +++ b/src/model/LibcalUtilisationSpaceSummary.js @@ -0,0 +1,90 @@ +/** + * UCL API + * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` + * + * The version of the OpenAPI document: 1.4.2 + * Contact: isd.apiteam@ucl.ac.uk + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + * + */ + +import ApiClient from '../ApiClient'; + +/** + * The LibcalUtilisationSpaceSummary model module. + * @module model/LibcalUtilisationSpaceSummary + * @version 1.4.2 + */ +class LibcalUtilisationSpaceSummary { + /** + * Constructs a new LibcalUtilisationSpaceSummary. + * @alias module:model/LibcalUtilisationSpaceSummary + */ + constructor() { + + LibcalUtilisationSpaceSummary.initialize(this); + } + + /** + * Initializes the fields of this object. + * This method is used by the constructors of any subclasses, in order to implement multiple inheritance (mix-ins). + * Only for internal use. + */ + static initialize(obj) { + } + + /** + * Constructs a LibcalUtilisationSpaceSummary from a plain JavaScript object, optionally creating a new instance. + * Copies all relevant properties from data to obj if supplied or a new instance if not. + * @param {Object} data The plain JavaScript object bearing properties of interest. + * @param {module:model/LibcalUtilisationSpaceSummary} obj Optional instance to populate. + * @return {module:model/LibcalUtilisationSpaceSummary} The populated LibcalUtilisationSpaceSummary instance. + */ + static constructFromObject(data, obj) { + if (data) { + obj = obj || new LibcalUtilisationSpaceSummary(); + + if (data.hasOwnProperty('active')) { + obj['active'] = ApiClient.convertToType(data['active'], 'Number'); + } + if (data.hasOwnProperty('bookable_count')) { + obj['bookable_count'] = ApiClient.convertToType(data['bookable_count'], 'Number'); + } + if (data.hasOwnProperty('total')) { + obj['total'] = ApiClient.convertToType(data['total'], 'Number'); + } + } + return obj; + } + + +} + +/** + * Number of active LibCal bookings of spaces + * @member {Number} active + */ +LibcalUtilisationSpaceSummary.prototype['active'] = undefined; + +/** + * Number of LibCal spaces available to be booked + * @member {Number} bookable_count + */ +LibcalUtilisationSpaceSummary.prototype['bookable_count'] = undefined; + +/** + * Total number of LibCal spaces in the location + * @member {Number} total + */ +LibcalUtilisationSpaceSummary.prototype['total'] = undefined; + + + + + + +export default LibcalUtilisationSpaceSummary; + diff --git a/src/model/LibcalZone.js b/src/model/LibcalZone.js new file mode 100644 index 00000000..529295e0 --- /dev/null +++ b/src/model/LibcalZone.js @@ -0,0 +1,81 @@ +/** + * UCL API + * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` + * + * The version of the OpenAPI document: 1.4.2 + * Contact: isd.apiteam@ucl.ac.uk + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + * + */ + +import ApiClient from '../ApiClient'; + +/** + * The LibcalZone model module. + * @module model/LibcalZone + * @version 1.4.2 + */ +class LibcalZone { + /** + * Constructs a new LibcalZone. + * @alias module:model/LibcalZone + */ + constructor() { + + LibcalZone.initialize(this); + } + + /** + * Initializes the fields of this object. + * This method is used by the constructors of any subclasses, in order to implement multiple inheritance (mix-ins). + * Only for internal use. + */ + static initialize(obj) { + } + + /** + * Constructs a LibcalZone from a plain JavaScript object, optionally creating a new instance. + * Copies all relevant properties from data to obj if supplied or a new instance if not. + * @param {Object} data The plain JavaScript object bearing properties of interest. + * @param {module:model/LibcalZone} obj Optional instance to populate. + * @return {module:model/LibcalZone} The populated LibcalZone instance. + */ + static constructFromObject(data, obj) { + if (data) { + obj = obj || new LibcalZone(); + + if (data.hasOwnProperty('id')) { + obj['id'] = ApiClient.convertToType(data['id'], 'Number'); + } + if (data.hasOwnProperty('name')) { + obj['name'] = ApiClient.convertToType(data['name'], 'String'); + } + } + return obj; + } + + +} + +/** + * LibCal Zone ID + * @member {Number} id + */ +LibcalZone.prototype['id'] = undefined; + +/** + * Name of the LibCal zone + * @member {String} name + */ +LibcalZone.prototype['name'] = undefined; + + + + + + +export default LibcalZone; + diff --git a/src/model/Location.js b/src/model/Location.js index d9730cd9..19a03681 100644 --- a/src/model/Location.js +++ b/src/model/Location.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -17,7 +17,7 @@ import LocationCoordinates from './LocationCoordinates'; /** * The Location model module. * @module model/Location - * @version 1.0.3 + * @version 1.4.2 */ class Location { /** diff --git a/src/model/LocationCoordinates.js b/src/model/LocationCoordinates.js index 882139e5..4f14c576 100644 --- a/src/model/LocationCoordinates.js +++ b/src/model/LocationCoordinates.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -16,7 +16,7 @@ import ApiClient from '../ApiClient'; /** * The LocationCoordinates model module. * @module model/LocationCoordinates - * @version 1.0.3 + * @version 1.4.2 */ class LocationCoordinates { /** diff --git a/src/model/Map.js b/src/model/Map.js index 548fe39d..e8a2d676 100644 --- a/src/model/Map.js +++ b/src/model/Map.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -16,7 +16,7 @@ import ApiClient from '../ApiClient'; /** * The Map model module. * @module model/Map - * @version 1.0.3 + * @version 1.4.2 */ class Map { /** diff --git a/src/model/MapWithSensors.js b/src/model/MapWithSensors.js index 5ed7aaab..6a82aaff 100644 --- a/src/model/MapWithSensors.js +++ b/src/model/MapWithSensors.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -17,7 +17,7 @@ import Sensor from './Sensor'; /** * The MapWithSensors model module. * @module model/MapWithSensors - * @version 1.0.3 + * @version 1.4.2 */ class MapWithSensors { /** diff --git a/src/model/Module.js b/src/model/Module.js index f5efeea5..b992acd6 100644 --- a/src/model/Module.js +++ b/src/model/Module.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -17,7 +17,7 @@ import Lecturer from './Lecturer'; /** * The Module model module. * @module model/Module - * @version 1.0.3 + * @version 1.4.2 */ class Module { /** diff --git a/src/model/ModuleDataCoursesModules.js b/src/model/ModuleDataCoursesModules.js index ebf7b9e3..4a1a2918 100644 --- a/src/model/ModuleDataCoursesModules.js +++ b/src/model/ModuleDataCoursesModules.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -17,7 +17,7 @@ import Instance from './Instance'; /** * The ModuleDataCoursesModules model module. * @module model/ModuleDataCoursesModules - * @version 1.0.3 + * @version 1.4.2 */ class ModuleDataCoursesModules { /** diff --git a/src/model/Period.js b/src/model/Period.js index 182f539f..6915eb6b 100644 --- a/src/model/Period.js +++ b/src/model/Period.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -18,7 +18,7 @@ import TeachingPeriods from './TeachingPeriods'; /** * The Period model module. * @module model/Period - * @version 1.0.3 + * @version 1.4.2 */ class Period { /** diff --git a/src/model/Person.js b/src/model/Person.js index 81f938e4..afe8aa6d 100644 --- a/src/model/Person.js +++ b/src/model/Person.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -16,7 +16,7 @@ import ApiClient from '../ApiClient'; /** * The Person model module. * @module model/Person - * @version 1.0.3 + * @version 1.4.2 */ class Person { /** diff --git a/src/model/Room.js b/src/model/Room.js index 53c87412..0f2977d0 100644 --- a/src/model/Room.js +++ b/src/model/Room.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -17,7 +17,7 @@ import RoomLocation from './RoomLocation'; /** * The Room model module. * @module model/Room - * @version 1.0.3 + * @version 1.4.2 */ class Room { /** diff --git a/src/model/RoomLocation.js b/src/model/RoomLocation.js index 38855336..53ab996d 100644 --- a/src/model/RoomLocation.js +++ b/src/model/RoomLocation.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -17,7 +17,7 @@ import LocationCoordinates from './LocationCoordinates'; /** * The RoomLocation model module. * @module model/RoomLocation - * @version 1.0.3 + * @version 1.4.2 */ class RoomLocation { /** diff --git a/src/model/SeatImage.js b/src/model/SeatImage.js index 4e2c2620..fa35d850 100644 --- a/src/model/SeatImage.js +++ b/src/model/SeatImage.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -17,7 +17,7 @@ import SeatImageCircle from './SeatImageCircle'; /** * The SeatImage model module. * @module model/SeatImage - * @version 1.0.3 + * @version 1.4.2 */ class SeatImage { /** diff --git a/src/model/SeatImageCircle.js b/src/model/SeatImageCircle.js index 5373d69d..ac297ca3 100644 --- a/src/model/SeatImageCircle.js +++ b/src/model/SeatImageCircle.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -16,7 +16,7 @@ import ApiClient from '../ApiClient'; /** * The SeatImageCircle model module. * @module model/SeatImageCircle - * @version 1.0.3 + * @version 1.4.2 */ class SeatImageCircle { /** diff --git a/src/model/Sensor.js b/src/model/Sensor.js index afc53cbc..91df868e 100644 --- a/src/model/Sensor.js +++ b/src/model/Sensor.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -16,7 +16,7 @@ import ApiClient from '../ApiClient'; /** * The Sensor model module. * @module model/Sensor - * @version 1.0.3 + * @version 1.4.2 */ class Sensor { /** diff --git a/src/model/SensorAverageSurvey.js b/src/model/SensorAverageSurvey.js index 2d463b45..b67a5e20 100644 --- a/src/model/SensorAverageSurvey.js +++ b/src/model/SensorAverageSurvey.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -17,7 +17,7 @@ import Average from './Average'; /** * The SensorAverageSurvey model module. * @module model/SensorAverageSurvey - * @version 1.0.3 + * @version 1.4.2 */ class SensorAverageSurvey { /** diff --git a/src/model/SummerSchool.js b/src/model/SummerSchool.js index 9f0e847e..e18fb809 100644 --- a/src/model/SummerSchool.js +++ b/src/model/SummerSchool.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -17,7 +17,7 @@ import SummerSchoolSessions from './SummerSchoolSessions'; /** * The SummerSchool model module. * @module model/SummerSchool - * @version 1.0.3 + * @version 1.4.2 */ class SummerSchool { /** diff --git a/src/model/SummerSchoolSessions.js b/src/model/SummerSchoolSessions.js index a1ff7ba5..39270d9b 100644 --- a/src/model/SummerSchoolSessions.js +++ b/src/model/SummerSchoolSessions.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -16,7 +16,7 @@ import ApiClient from '../ApiClient'; /** * The SummerSchoolSessions model module. * @module model/SummerSchoolSessions - * @version 1.0.3 + * @version 1.4.2 */ class SummerSchoolSessions { /** diff --git a/src/model/Survey.js b/src/model/Survey.js index 9162371f..d0249b13 100644 --- a/src/model/Survey.js +++ b/src/model/Survey.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -17,7 +17,7 @@ import SurveyLocation from './SurveyLocation'; /** * The Survey model module. * @module model/Survey - * @version 1.0.3 + * @version 1.4.2 */ class Survey { /** diff --git a/src/model/SurveyLocation.js b/src/model/SurveyLocation.js index 9c19371e..4d4a4676 100644 --- a/src/model/SurveyLocation.js +++ b/src/model/SurveyLocation.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -17,7 +17,7 @@ import SurveyLocationCoordinates from './SurveyLocationCoordinates'; /** * The SurveyLocation model module. * @module model/SurveyLocation - * @version 1.0.3 + * @version 1.4.2 */ class SurveyLocation { /** diff --git a/src/model/SurveyLocationCoordinates.js b/src/model/SurveyLocationCoordinates.js index 8640c596..73df249c 100644 --- a/src/model/SurveyLocationCoordinates.js +++ b/src/model/SurveyLocationCoordinates.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -16,7 +16,7 @@ import ApiClient from '../ApiClient'; /** * The SurveyLocationCoordinates model module. * @module model/SurveyLocationCoordinates - * @version 1.0.3 + * @version 1.4.2 */ class SurveyLocationCoordinates { /** diff --git a/src/model/SurveyWithMaps.js b/src/model/SurveyWithMaps.js index 37b6dc10..97158d95 100644 --- a/src/model/SurveyWithMaps.js +++ b/src/model/SurveyWithMaps.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -17,7 +17,7 @@ import AverageWithNameAndId from './AverageWithNameAndId'; /** * The SurveyWithMaps model module. * @module model/SurveyWithMaps - * @version 1.0.3 + * @version 1.4.2 */ class SurveyWithMaps { /** diff --git a/src/model/Svg.js b/src/model/Svg.js index 1c37bf21..12025014 100644 --- a/src/model/Svg.js +++ b/src/model/Svg.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -17,7 +17,7 @@ import SvgG from './SvgG'; /** * The Svg model module. * @module model/Svg - * @version 1.0.3 + * @version 1.4.2 */ class Svg { /** diff --git a/src/model/SvgG.js b/src/model/SvgG.js index a9ef4301..62360987 100644 --- a/src/model/SvgG.js +++ b/src/model/SvgG.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -17,7 +17,7 @@ import SvgGImage from './SvgGImage'; /** * The SvgG model module. * @module model/SvgG - * @version 1.0.3 + * @version 1.4.2 */ class SvgG { /** diff --git a/src/model/SvgGImage.js b/src/model/SvgGImage.js index c5a87c8d..1a68fa65 100644 --- a/src/model/SvgGImage.js +++ b/src/model/SvgGImage.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -17,7 +17,7 @@ import SeatImage from './SeatImage'; /** * The SvgGImage model module. * @module model/SvgGImage - * @version 1.0.3 + * @version 1.4.2 */ class SvgGImage { /** diff --git a/src/model/TeachingPeriods.js b/src/model/TeachingPeriods.js index 417cc239..88b12cbf 100644 --- a/src/model/TeachingPeriods.js +++ b/src/model/TeachingPeriods.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -16,7 +16,7 @@ import ApiClient from '../ApiClient'; /** * The TeachingPeriods model module. * @module model/TeachingPeriods - * @version 1.0.3 + * @version 1.4.2 */ class TeachingPeriods { /** diff --git a/src/model/Timetable.js b/src/model/Timetable.js index f88a509d..7fc918b1 100644 --- a/src/model/Timetable.js +++ b/src/model/Timetable.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -17,7 +17,7 @@ import Event from './Event'; /** * The Timetable model module. * @module model/Timetable - * @version 1.0.3 + * @version 1.4.2 */ class Timetable { /** diff --git a/src/model/UserData.js b/src/model/UserData.js index 622fbce0..88624e88 100644 --- a/src/model/UserData.js +++ b/src/model/UserData.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -16,7 +16,7 @@ import ApiClient from '../ApiClient'; /** * The UserData model module. * @module model/UserData - * @version 1.0.3 + * @version 1.4.2 */ class UserData { /** diff --git a/test/api/AnalyticsApi.spec.js b/test/api/AnalyticsApi.spec.js index 8e63fbf0..0c848083 100644 --- a/test/api/AnalyticsApi.spec.js +++ b/test/api/AnalyticsApi.spec.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/api/LibCalApi.spec.js b/test/api/LibCalApi.spec.js new file mode 100644 index 00000000..9f46c3f3 --- /dev/null +++ b/test/api/LibCalApi.spec.js @@ -0,0 +1,213 @@ +/** + * UCL API + * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` + * + * The version of the OpenAPI document: 1.4.2 + * Contact: isd.apiteam@ucl.ac.uk + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + * + */ + +(function(root, factory) { + if (typeof define === 'function' && define.amd) { + // AMD. + define(['expect.js', process.cwd()+'/src/index'], factory); + } else if (typeof module === 'object' && module.exports) { + // CommonJS-like environments that support module.exports, like Node. + factory(require('expect.js'), require(process.cwd()+'/src/index')); + } else { + // Browser globals (root is window) + factory(root.expect, root.uclapi); + } +}(this, function(expect, uclapi) { + 'use strict'; + + var instance; + + beforeEach(function() { + instance = new uclapi.LibCalApi(); + }); + + var getProperty = function(object, getter, property) { + // Use getter method if present; otherwise, get the property directly. + if (typeof object[getter] === 'function') + return object[getter](); + else + return object[property]; + } + + var setProperty = function(object, setter, property, value) { + // Use setter method if present; otherwise, set the property directly. + if (typeof object[setter] === 'function') + object[setter](value); + else + object[property] = value; + } + + describe('LibCalApi', function() { + describe('libcalSpaceBookingsGet', function() { + it('should call libcalSpaceBookingsGet successfully', function(done) { + //uncomment below and update the code to test libcalSpaceBookingsGet + //instance.libcalSpaceBookingsGet(function(error) { + // if (error) throw error; + //expect().to.be(); + //}); + done(); + }); + }); + describe('libcalSpaceCancelPost', function() { + it('should call libcalSpaceCancelPost successfully', function(done) { + //uncomment below and update the code to test libcalSpaceCancelPost + //instance.libcalSpaceCancelPost(function(error) { + // if (error) throw error; + //expect().to.be(); + //}); + done(); + }); + }); + describe('libcalSpaceCategoriesGet', function() { + it('should call libcalSpaceCategoriesGet successfully', function(done) { + //uncomment below and update the code to test libcalSpaceCategoriesGet + //instance.libcalSpaceCategoriesGet(function(error) { + // if (error) throw error; + //expect().to.be(); + //}); + done(); + }); + }); + describe('libcalSpaceCategoryGet', function() { + it('should call libcalSpaceCategoryGet successfully', function(done) { + //uncomment below and update the code to test libcalSpaceCategoryGet + //instance.libcalSpaceCategoryGet(function(error) { + // if (error) throw error; + //expect().to.be(); + //}); + done(); + }); + }); + describe('libcalSpaceFormGet', function() { + it('should call libcalSpaceFormGet successfully', function(done) { + //uncomment below and update the code to test libcalSpaceFormGet + //instance.libcalSpaceFormGet(function(error) { + // if (error) throw error; + //expect().to.be(); + //}); + done(); + }); + }); + describe('libcalSpaceItemGet', function() { + it('should call libcalSpaceItemGet successfully', function(done) { + //uncomment below and update the code to test libcalSpaceItemGet + //instance.libcalSpaceItemGet(function(error) { + // if (error) throw error; + //expect().to.be(); + //}); + done(); + }); + }); + describe('libcalSpaceLocationsGet', function() { + it('should call libcalSpaceLocationsGet successfully', function(done) { + //uncomment below and update the code to test libcalSpaceLocationsGet + //instance.libcalSpaceLocationsGet(function(error) { + // if (error) throw error; + //expect().to.be(); + //}); + done(); + }); + }); + describe('libcalSpaceNicknameGet', function() { + it('should call libcalSpaceNicknameGet successfully', function(done) { + //uncomment below and update the code to test libcalSpaceNicknameGet + //instance.libcalSpaceNicknameGet(function(error) { + // if (error) throw error; + //expect().to.be(); + //}); + done(); + }); + }); + describe('libcalSpacePersonalBookingsGet', function() { + it('should call libcalSpacePersonalBookingsGet successfully', function(done) { + //uncomment below and update the code to test libcalSpacePersonalBookingsGet + //instance.libcalSpacePersonalBookingsGet(function(error) { + // if (error) throw error; + //expect().to.be(); + //}); + done(); + }); + }); + describe('libcalSpaceQuestionGet', function() { + it('should call libcalSpaceQuestionGet successfully', function(done) { + //uncomment below and update the code to test libcalSpaceQuestionGet + //instance.libcalSpaceQuestionGet(function(error) { + // if (error) throw error; + //expect().to.be(); + //}); + done(); + }); + }); + describe('libcalSpaceReservePost', function() { + it('should call libcalSpaceReservePost successfully', function(done) { + //uncomment below and update the code to test libcalSpaceReservePost + //instance.libcalSpaceReservePost(function(error) { + // if (error) throw error; + //expect().to.be(); + //}); + done(); + }); + }); + describe('libcalSpaceSeatGet', function() { + it('should call libcalSpaceSeatGet successfully', function(done) { + //uncomment below and update the code to test libcalSpaceSeatGet + //instance.libcalSpaceSeatGet(function(error) { + // if (error) throw error; + //expect().to.be(); + //}); + done(); + }); + }); + describe('libcalSpaceSeatsGet', function() { + it('should call libcalSpaceSeatsGet successfully', function(done) { + //uncomment below and update the code to test libcalSpaceSeatsGet + //instance.libcalSpaceSeatsGet(function(error) { + // if (error) throw error; + //expect().to.be(); + //}); + done(); + }); + }); + describe('libcalSpaceUtilizationGet', function() { + it('should call libcalSpaceUtilizationGet successfully', function(done) { + //uncomment below and update the code to test libcalSpaceUtilizationGet + //instance.libcalSpaceUtilizationGet(function(error) { + // if (error) throw error; + //expect().to.be(); + //}); + done(); + }); + }); + describe('libcalSpaceZoneGet', function() { + it('should call libcalSpaceZoneGet successfully', function(done) { + //uncomment below and update the code to test libcalSpaceZoneGet + //instance.libcalSpaceZoneGet(function(error) { + // if (error) throw error; + //expect().to.be(); + //}); + done(); + }); + }); + describe('libcalSpaceZonesGet', function() { + it('should call libcalSpaceZonesGet successfully', function(done) { + //uncomment below and update the code to test libcalSpaceZonesGet + //instance.libcalSpaceZonesGet(function(error) { + // if (error) throw error; + //expect().to.be(); + //}); + done(); + }); + }); + }); + +})); diff --git a/test/api/OAuthApi.spec.js b/test/api/OAuthApi.spec.js index b1e9cf14..13b26ef8 100644 --- a/test/api/OAuthApi.spec.js +++ b/test/api/OAuthApi.spec.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/api/ResourcesApi.spec.js b/test/api/ResourcesApi.spec.js index 3e37c17d..dd753243 100644 --- a/test/api/ResourcesApi.spec.js +++ b/test/api/ResourcesApi.spec.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/api/RoomBookingsApi.spec.js b/test/api/RoomBookingsApi.spec.js index 7c56b5ee..8cab25a4 100644 --- a/test/api/RoomBookingsApi.spec.js +++ b/test/api/RoomBookingsApi.spec.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/api/SearchApi.spec.js b/test/api/SearchApi.spec.js index eb493218..291dc288 100644 --- a/test/api/SearchApi.spec.js +++ b/test/api/SearchApi.spec.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/api/TimetableApi.spec.js b/test/api/TimetableApi.spec.js index 9c2b0bd5..deebb309 100644 --- a/test/api/TimetableApi.spec.js +++ b/test/api/TimetableApi.spec.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/api/WorkspacesApi.spec.js b/test/api/WorkspacesApi.spec.js index f3e7c25e..cfaa27e2 100644 --- a/test/api/WorkspacesApi.spec.js +++ b/test/api/WorkspacesApi.spec.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/Average.spec.js b/test/model/Average.spec.js index ad0eaef4..693ab387 100644 --- a/test/model/Average.spec.js +++ b/test/model/Average.spec.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/AverageWithNameAndId.spec.js b/test/model/AverageWithNameAndId.spec.js index ee1c91a9..16b9ba6d 100644 --- a/test/model/AverageWithNameAndId.spec.js +++ b/test/model/AverageWithNameAndId.spec.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/Booking.spec.js b/test/model/Booking.spec.js index 75ca28fe..8fbc67a2 100644 --- a/test/model/Booking.spec.js +++ b/test/model/Booking.spec.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/Course.spec.js b/test/model/Course.spec.js index d5cd8b79..afd44036 100644 --- a/test/model/Course.spec.js +++ b/test/model/Course.spec.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/Delivery.spec.js b/test/model/Delivery.spec.js index 0127252c..ca544828 100644 --- a/test/model/Delivery.spec.js +++ b/test/model/Delivery.spec.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/Department.spec.js b/test/model/Department.spec.js index 2d7ac3f1..61103b56 100644 --- a/test/model/Department.spec.js +++ b/test/model/Department.spec.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/DesktopData.spec.js b/test/model/DesktopData.spec.js index 5bee587f..843d1f5f 100644 --- a/test/model/DesktopData.spec.js +++ b/test/model/DesktopData.spec.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/DesktopDataLocation.spec.js b/test/model/DesktopDataLocation.spec.js index ee0d847e..b9aca851 100644 --- a/test/model/DesktopDataLocation.spec.js +++ b/test/model/DesktopDataLocation.spec.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/Equipment.spec.js b/test/model/Equipment.spec.js index 3915883c..b430476b 100644 --- a/test/model/Equipment.spec.js +++ b/test/model/Equipment.spec.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/Error.spec.js b/test/model/Error.spec.js index 65dfe6ff..2921722b 100644 --- a/test/model/Error.spec.js +++ b/test/model/Error.spec.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/Event.spec.js b/test/model/Event.spec.js index f68c3a4a..e4cbbafa 100644 --- a/test/model/Event.spec.js +++ b/test/model/Event.spec.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/HistoricalSensor.spec.js b/test/model/HistoricalSensor.spec.js index d1c1745e..b2bab566 100644 --- a/test/model/HistoricalSensor.spec.js +++ b/test/model/HistoricalSensor.spec.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/HistoricalSurvey.spec.js b/test/model/HistoricalSurvey.spec.js index 77681909..af8f5abd 100644 --- a/test/model/HistoricalSurvey.spec.js +++ b/test/model/HistoricalSurvey.spec.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/HistoricalSurveyData.spec.js b/test/model/HistoricalSurveyData.spec.js index 3e7499ed..5f5bc91e 100644 --- a/test/model/HistoricalSurveyData.spec.js +++ b/test/model/HistoricalSurveyData.spec.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/InlineResponse200.spec.js b/test/model/InlineResponse200.spec.js index 2a17d072..1cdd9108 100644 --- a/test/model/InlineResponse200.spec.js +++ b/test/model/InlineResponse200.spec.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/InlineResponse2001.spec.js b/test/model/InlineResponse2001.spec.js index e5286063..773d6a27 100644 --- a/test/model/InlineResponse2001.spec.js +++ b/test/model/InlineResponse2001.spec.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/InlineResponse20010.spec.js b/test/model/InlineResponse20010.spec.js index a8f275b9..cd0958b2 100644 --- a/test/model/InlineResponse20010.spec.js +++ b/test/model/InlineResponse20010.spec.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/InlineResponse20011.spec.js b/test/model/InlineResponse20011.spec.js index 00ee08ff..29c9cd64 100644 --- a/test/model/InlineResponse20011.spec.js +++ b/test/model/InlineResponse20011.spec.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/InlineResponse20012.spec.js b/test/model/InlineResponse20012.spec.js index fb0e944f..092f2784 100644 --- a/test/model/InlineResponse20012.spec.js +++ b/test/model/InlineResponse20012.spec.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/InlineResponse20013.spec.js b/test/model/InlineResponse20013.spec.js index 67a56db0..09723891 100644 --- a/test/model/InlineResponse20013.spec.js +++ b/test/model/InlineResponse20013.spec.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/InlineResponse20014.spec.js b/test/model/InlineResponse20014.spec.js index db71f3cf..b65ab3c5 100644 --- a/test/model/InlineResponse20014.spec.js +++ b/test/model/InlineResponse20014.spec.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/InlineResponse20015.spec.js b/test/model/InlineResponse20015.spec.js index b082bfe5..be6cceec 100644 --- a/test/model/InlineResponse20015.spec.js +++ b/test/model/InlineResponse20015.spec.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/InlineResponse20016.spec.js b/test/model/InlineResponse20016.spec.js index 7f5d948c..e9bd2f35 100644 --- a/test/model/InlineResponse20016.spec.js +++ b/test/model/InlineResponse20016.spec.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/InlineResponse20017.spec.js b/test/model/InlineResponse20017.spec.js index 8ef86755..cd1ba7dc 100644 --- a/test/model/InlineResponse20017.spec.js +++ b/test/model/InlineResponse20017.spec.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/InlineResponse20018.spec.js b/test/model/InlineResponse20018.spec.js index 9bd391d5..486f4356 100644 --- a/test/model/InlineResponse20018.spec.js +++ b/test/model/InlineResponse20018.spec.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/InlineResponse20018Data.spec.js b/test/model/InlineResponse20018Data.spec.js index 513d2686..0323e686 100644 --- a/test/model/InlineResponse20018Data.spec.js +++ b/test/model/InlineResponse20018Data.spec.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/InlineResponse20019.spec.js b/test/model/InlineResponse20019.spec.js index 56190d7c..7dd6e527 100644 --- a/test/model/InlineResponse20019.spec.js +++ b/test/model/InlineResponse20019.spec.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/InlineResponse20019Data.spec.js b/test/model/InlineResponse20019Data.spec.js index b7439c34..b579f6c0 100644 --- a/test/model/InlineResponse20019Data.spec.js +++ b/test/model/InlineResponse20019Data.spec.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/InlineResponse2002.spec.js b/test/model/InlineResponse2002.spec.js index cf2832b1..9f56a7c3 100644 --- a/test/model/InlineResponse2002.spec.js +++ b/test/model/InlineResponse2002.spec.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/InlineResponse20020.spec.js b/test/model/InlineResponse20020.spec.js index d682716e..2e5bd1cc 100644 --- a/test/model/InlineResponse20020.spec.js +++ b/test/model/InlineResponse20020.spec.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/InlineResponse20020Surveys.spec.js b/test/model/InlineResponse20020Surveys.spec.js index 1a1b7983..b0cfbe4d 100644 --- a/test/model/InlineResponse20020Surveys.spec.js +++ b/test/model/InlineResponse20020Surveys.spec.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/InlineResponse20021.spec.js b/test/model/InlineResponse20021.spec.js index ef333e2c..a3fa4566 100644 --- a/test/model/InlineResponse20021.spec.js +++ b/test/model/InlineResponse20021.spec.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/InlineResponse20022.spec.js b/test/model/InlineResponse20022.spec.js index f7e3dc08..9a7e3d67 100644 --- a/test/model/InlineResponse20022.spec.js +++ b/test/model/InlineResponse20022.spec.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/InlineResponse20023.spec.js b/test/model/InlineResponse20023.spec.js index d1866966..5a7eee29 100644 --- a/test/model/InlineResponse20023.spec.js +++ b/test/model/InlineResponse20023.spec.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/InlineResponse20023Data.spec.js b/test/model/InlineResponse20023Data.spec.js index 3c704dc3..8bdd3962 100644 --- a/test/model/InlineResponse20023Data.spec.js +++ b/test/model/InlineResponse20023Data.spec.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/InlineResponse20024.spec.js b/test/model/InlineResponse20024.spec.js index 1e27acb3..aaebaedb 100644 --- a/test/model/InlineResponse20024.spec.js +++ b/test/model/InlineResponse20024.spec.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/InlineResponse20024Data.spec.js b/test/model/InlineResponse20024Data.spec.js index 382716e6..7deeab18 100644 --- a/test/model/InlineResponse20024Data.spec.js +++ b/test/model/InlineResponse20024Data.spec.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/InlineResponse20025.spec.js b/test/model/InlineResponse20025.spec.js index d62f790e..7e0fd143 100644 --- a/test/model/InlineResponse20025.spec.js +++ b/test/model/InlineResponse20025.spec.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/InlineResponse20026.spec.js b/test/model/InlineResponse20026.spec.js index d365aeca..82cfa4f3 100644 --- a/test/model/InlineResponse20026.spec.js +++ b/test/model/InlineResponse20026.spec.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/InlineResponse20026Data.spec.js b/test/model/InlineResponse20026Data.spec.js index fcb678f5..834f0731 100644 --- a/test/model/InlineResponse20026Data.spec.js +++ b/test/model/InlineResponse20026Data.spec.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/InlineResponse20027.spec.js b/test/model/InlineResponse20027.spec.js new file mode 100644 index 00000000..58375f23 --- /dev/null +++ b/test/model/InlineResponse20027.spec.js @@ -0,0 +1,71 @@ +/** + * UCL API + * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` + * + * The version of the OpenAPI document: 1.4.2 + * Contact: isd.apiteam@ucl.ac.uk + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + * + */ + +(function(root, factory) { + if (typeof define === 'function' && define.amd) { + // AMD. + define(['expect.js', process.cwd()+'/src/index'], factory); + } else if (typeof module === 'object' && module.exports) { + // CommonJS-like environments that support module.exports, like Node. + factory(require('expect.js'), require(process.cwd()+'/src/index')); + } else { + // Browser globals (root is window) + factory(root.expect, root.uclapi); + } +}(this, function(expect, uclapi) { + 'use strict'; + + var instance; + + beforeEach(function() { + instance = new uclapi.InlineResponse20027(); + }); + + var getProperty = function(object, getter, property) { + // Use getter method if present; otherwise, get the property directly. + if (typeof object[getter] === 'function') + return object[getter](); + else + return object[property]; + } + + var setProperty = function(object, setter, property, value) { + // Use setter method if present; otherwise, set the property directly. + if (typeof object[setter] === 'function') + object[setter](value); + else + object[property] = value; + } + + describe('InlineResponse20027', function() { + it('should create an instance of InlineResponse20027', function() { + // uncomment below and update the code to test InlineResponse20027 + //var instane = new uclapi.InlineResponse20027(); + //expect(instance).to.be.a(uclapi.InlineResponse20027); + }); + + it('should have the property ok (base name: "ok")', function() { + // uncomment below and update the code to test the property ok + //var instance = new uclapi.InlineResponse20027(); + //expect(instance).to.be(); + }); + + it('should have the property data (base name: "data")', function() { + // uncomment below and update the code to test the property data + //var instance = new uclapi.InlineResponse20027(); + //expect(instance).to.be(); + }); + + }); + +})); diff --git a/test/model/InlineResponse20028.spec.js b/test/model/InlineResponse20028.spec.js new file mode 100644 index 00000000..edc21d2a --- /dev/null +++ b/test/model/InlineResponse20028.spec.js @@ -0,0 +1,71 @@ +/** + * UCL API + * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` + * + * The version of the OpenAPI document: 1.4.2 + * Contact: isd.apiteam@ucl.ac.uk + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + * + */ + +(function(root, factory) { + if (typeof define === 'function' && define.amd) { + // AMD. + define(['expect.js', process.cwd()+'/src/index'], factory); + } else if (typeof module === 'object' && module.exports) { + // CommonJS-like environments that support module.exports, like Node. + factory(require('expect.js'), require(process.cwd()+'/src/index')); + } else { + // Browser globals (root is window) + factory(root.expect, root.uclapi); + } +}(this, function(expect, uclapi) { + 'use strict'; + + var instance; + + beforeEach(function() { + instance = new uclapi.InlineResponse20028(); + }); + + var getProperty = function(object, getter, property) { + // Use getter method if present; otherwise, get the property directly. + if (typeof object[getter] === 'function') + return object[getter](); + else + return object[property]; + } + + var setProperty = function(object, setter, property, value) { + // Use setter method if present; otherwise, set the property directly. + if (typeof object[setter] === 'function') + object[setter](value); + else + object[property] = value; + } + + describe('InlineResponse20028', function() { + it('should create an instance of InlineResponse20028', function() { + // uncomment below and update the code to test InlineResponse20028 + //var instane = new uclapi.InlineResponse20028(); + //expect(instance).to.be.a(uclapi.InlineResponse20028); + }); + + it('should have the property ok (base name: "ok")', function() { + // uncomment below and update the code to test the property ok + //var instance = new uclapi.InlineResponse20028(); + //expect(instance).to.be(); + }); + + it('should have the property categories (base name: "categories")', function() { + // uncomment below and update the code to test the property categories + //var instance = new uclapi.InlineResponse20028(); + //expect(instance).to.be(); + }); + + }); + +})); diff --git a/test/model/InlineResponse20029.spec.js b/test/model/InlineResponse20029.spec.js new file mode 100644 index 00000000..417c0257 --- /dev/null +++ b/test/model/InlineResponse20029.spec.js @@ -0,0 +1,71 @@ +/** + * UCL API + * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` + * + * The version of the OpenAPI document: 1.4.2 + * Contact: isd.apiteam@ucl.ac.uk + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + * + */ + +(function(root, factory) { + if (typeof define === 'function' && define.amd) { + // AMD. + define(['expect.js', process.cwd()+'/src/index'], factory); + } else if (typeof module === 'object' && module.exports) { + // CommonJS-like environments that support module.exports, like Node. + factory(require('expect.js'), require(process.cwd()+'/src/index')); + } else { + // Browser globals (root is window) + factory(root.expect, root.uclapi); + } +}(this, function(expect, uclapi) { + 'use strict'; + + var instance; + + beforeEach(function() { + instance = new uclapi.InlineResponse20029(); + }); + + var getProperty = function(object, getter, property) { + // Use getter method if present; otherwise, get the property directly. + if (typeof object[getter] === 'function') + return object[getter](); + else + return object[property]; + } + + var setProperty = function(object, setter, property, value) { + // Use setter method if present; otherwise, set the property directly. + if (typeof object[setter] === 'function') + object[setter](value); + else + object[property] = value; + } + + describe('InlineResponse20029', function() { + it('should create an instance of InlineResponse20029', function() { + // uncomment below and update the code to test InlineResponse20029 + //var instane = new uclapi.InlineResponse20029(); + //expect(instance).to.be.a(uclapi.InlineResponse20029); + }); + + it('should have the property ok (base name: "ok")', function() { + // uncomment below and update the code to test the property ok + //var instance = new uclapi.InlineResponse20029(); + //expect(instance).to.be(); + }); + + it('should have the property categories (base name: "categories")', function() { + // uncomment below and update the code to test the property categories + //var instance = new uclapi.InlineResponse20029(); + //expect(instance).to.be(); + }); + + }); + +})); diff --git a/test/model/InlineResponse20029Categories.spec.js b/test/model/InlineResponse20029Categories.spec.js new file mode 100644 index 00000000..ee7bf799 --- /dev/null +++ b/test/model/InlineResponse20029Categories.spec.js @@ -0,0 +1,83 @@ +/** + * UCL API + * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` + * + * The version of the OpenAPI document: 1.4.2 + * Contact: isd.apiteam@ucl.ac.uk + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + * + */ + +(function(root, factory) { + if (typeof define === 'function' && define.amd) { + // AMD. + define(['expect.js', process.cwd()+'/src/index'], factory); + } else if (typeof module === 'object' && module.exports) { + // CommonJS-like environments that support module.exports, like Node. + factory(require('expect.js'), require(process.cwd()+'/src/index')); + } else { + // Browser globals (root is window) + factory(root.expect, root.uclapi); + } +}(this, function(expect, uclapi) { + 'use strict'; + + var instance; + + beforeEach(function() { + instance = new uclapi.InlineResponse20029Categories(); + }); + + var getProperty = function(object, getter, property) { + // Use getter method if present; otherwise, get the property directly. + if (typeof object[getter] === 'function') + return object[getter](); + else + return object[property]; + } + + var setProperty = function(object, setter, property, value) { + // Use setter method if present; otherwise, set the property directly. + if (typeof object[setter] === 'function') + object[setter](value); + else + object[property] = value; + } + + describe('InlineResponse20029Categories', function() { + it('should create an instance of InlineResponse20029Categories', function() { + // uncomment below and update the code to test InlineResponse20029Categories + //var instane = new uclapi.InlineResponse20029Categories(); + //expect(instance).to.be.a(uclapi.InlineResponse20029Categories); + }); + + it('should have the property cid (base name: "cid")', function() { + // uncomment below and update the code to test the property cid + //var instance = new uclapi.InlineResponse20029Categories(); + //expect(instance).to.be(); + }); + + it('should have the property formid (base name: "formid")', function() { + // uncomment below and update the code to test the property formid + //var instance = new uclapi.InlineResponse20029Categories(); + //expect(instance).to.be(); + }); + + it('should have the property _public (base name: "public")', function() { + // uncomment below and update the code to test the property _public + //var instance = new uclapi.InlineResponse20029Categories(); + //expect(instance).to.be(); + }); + + it('should have the property items (base name: "items")', function() { + // uncomment below and update the code to test the property items + //var instance = new uclapi.InlineResponse20029Categories(); + //expect(instance).to.be(); + }); + + }); + +})); diff --git a/test/model/InlineResponse2003.spec.js b/test/model/InlineResponse2003.spec.js index 75c39664..b1c61d4a 100644 --- a/test/model/InlineResponse2003.spec.js +++ b/test/model/InlineResponse2003.spec.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/InlineResponse20030.spec.js b/test/model/InlineResponse20030.spec.js new file mode 100644 index 00000000..b6f83295 --- /dev/null +++ b/test/model/InlineResponse20030.spec.js @@ -0,0 +1,71 @@ +/** + * UCL API + * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` + * + * The version of the OpenAPI document: 1.4.2 + * Contact: isd.apiteam@ucl.ac.uk + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + * + */ + +(function(root, factory) { + if (typeof define === 'function' && define.amd) { + // AMD. + define(['expect.js', process.cwd()+'/src/index'], factory); + } else if (typeof module === 'object' && module.exports) { + // CommonJS-like environments that support module.exports, like Node. + factory(require('expect.js'), require(process.cwd()+'/src/index')); + } else { + // Browser globals (root is window) + factory(root.expect, root.uclapi); + } +}(this, function(expect, uclapi) { + 'use strict'; + + var instance; + + beforeEach(function() { + instance = new uclapi.InlineResponse20030(); + }); + + var getProperty = function(object, getter, property) { + // Use getter method if present; otherwise, get the property directly. + if (typeof object[getter] === 'function') + return object[getter](); + else + return object[property]; + } + + var setProperty = function(object, setter, property, value) { + // Use setter method if present; otherwise, set the property directly. + if (typeof object[setter] === 'function') + object[setter](value); + else + object[property] = value; + } + + describe('InlineResponse20030', function() { + it('should create an instance of InlineResponse20030', function() { + // uncomment below and update the code to test InlineResponse20030 + //var instane = new uclapi.InlineResponse20030(); + //expect(instance).to.be.a(uclapi.InlineResponse20030); + }); + + it('should have the property ok (base name: "ok")', function() { + // uncomment below and update the code to test the property ok + //var instance = new uclapi.InlineResponse20030(); + //expect(instance).to.be(); + }); + + it('should have the property forms (base name: "forms")', function() { + // uncomment below and update the code to test the property forms + //var instance = new uclapi.InlineResponse20030(); + //expect(instance).to.be(); + }); + + }); + +})); diff --git a/test/model/InlineResponse20031.spec.js b/test/model/InlineResponse20031.spec.js new file mode 100644 index 00000000..f72bc3d7 --- /dev/null +++ b/test/model/InlineResponse20031.spec.js @@ -0,0 +1,71 @@ +/** + * UCL API + * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` + * + * The version of the OpenAPI document: 1.4.2 + * Contact: isd.apiteam@ucl.ac.uk + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + * + */ + +(function(root, factory) { + if (typeof define === 'function' && define.amd) { + // AMD. + define(['expect.js', process.cwd()+'/src/index'], factory); + } else if (typeof module === 'object' && module.exports) { + // CommonJS-like environments that support module.exports, like Node. + factory(require('expect.js'), require(process.cwd()+'/src/index')); + } else { + // Browser globals (root is window) + factory(root.expect, root.uclapi); + } +}(this, function(expect, uclapi) { + 'use strict'; + + var instance; + + beforeEach(function() { + instance = new uclapi.InlineResponse20031(); + }); + + var getProperty = function(object, getter, property) { + // Use getter method if present; otherwise, get the property directly. + if (typeof object[getter] === 'function') + return object[getter](); + else + return object[property]; + } + + var setProperty = function(object, setter, property, value) { + // Use setter method if present; otherwise, set the property directly. + if (typeof object[setter] === 'function') + object[setter](value); + else + object[property] = value; + } + + describe('InlineResponse20031', function() { + it('should create an instance of InlineResponse20031', function() { + // uncomment below and update the code to test InlineResponse20031 + //var instane = new uclapi.InlineResponse20031(); + //expect(instance).to.be.a(uclapi.InlineResponse20031); + }); + + it('should have the property ok (base name: "ok")', function() { + // uncomment below and update the code to test the property ok + //var instance = new uclapi.InlineResponse20031(); + //expect(instance).to.be(); + }); + + it('should have the property questions (base name: "questions")', function() { + // uncomment below and update the code to test the property questions + //var instance = new uclapi.InlineResponse20031(); + //expect(instance).to.be(); + }); + + }); + +})); diff --git a/test/model/InlineResponse20032.spec.js b/test/model/InlineResponse20032.spec.js new file mode 100644 index 00000000..2d12a744 --- /dev/null +++ b/test/model/InlineResponse20032.spec.js @@ -0,0 +1,71 @@ +/** + * UCL API + * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` + * + * The version of the OpenAPI document: 1.4.2 + * Contact: isd.apiteam@ucl.ac.uk + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + * + */ + +(function(root, factory) { + if (typeof define === 'function' && define.amd) { + // AMD. + define(['expect.js', process.cwd()+'/src/index'], factory); + } else if (typeof module === 'object' && module.exports) { + // CommonJS-like environments that support module.exports, like Node. + factory(require('expect.js'), require(process.cwd()+'/src/index')); + } else { + // Browser globals (root is window) + factory(root.expect, root.uclapi); + } +}(this, function(expect, uclapi) { + 'use strict'; + + var instance; + + beforeEach(function() { + instance = new uclapi.InlineResponse20032(); + }); + + var getProperty = function(object, getter, property) { + // Use getter method if present; otherwise, get the property directly. + if (typeof object[getter] === 'function') + return object[getter](); + else + return object[property]; + } + + var setProperty = function(object, setter, property, value) { + // Use setter method if present; otherwise, set the property directly. + if (typeof object[setter] === 'function') + object[setter](value); + else + object[property] = value; + } + + describe('InlineResponse20032', function() { + it('should create an instance of InlineResponse20032', function() { + // uncomment below and update the code to test InlineResponse20032 + //var instane = new uclapi.InlineResponse20032(); + //expect(instance).to.be.a(uclapi.InlineResponse20032); + }); + + it('should have the property ok (base name: "ok")', function() { + // uncomment below and update the code to test the property ok + //var instance = new uclapi.InlineResponse20032(); + //expect(instance).to.be(); + }); + + it('should have the property questions (base name: "questions")', function() { + // uncomment below and update the code to test the property questions + //var instance = new uclapi.InlineResponse20032(); + //expect(instance).to.be(); + }); + + }); + +})); diff --git a/test/model/InlineResponse20033.spec.js b/test/model/InlineResponse20033.spec.js new file mode 100644 index 00000000..3972de77 --- /dev/null +++ b/test/model/InlineResponse20033.spec.js @@ -0,0 +1,71 @@ +/** + * UCL API + * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` + * + * The version of the OpenAPI document: 1.4.2 + * Contact: isd.apiteam@ucl.ac.uk + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + * + */ + +(function(root, factory) { + if (typeof define === 'function' && define.amd) { + // AMD. + define(['expect.js', process.cwd()+'/src/index'], factory); + } else if (typeof module === 'object' && module.exports) { + // CommonJS-like environments that support module.exports, like Node. + factory(require('expect.js'), require(process.cwd()+'/src/index')); + } else { + // Browser globals (root is window) + factory(root.expect, root.uclapi); + } +}(this, function(expect, uclapi) { + 'use strict'; + + var instance; + + beforeEach(function() { + instance = new uclapi.InlineResponse20033(); + }); + + var getProperty = function(object, getter, property) { + // Use getter method if present; otherwise, get the property directly. + if (typeof object[getter] === 'function') + return object[getter](); + else + return object[property]; + } + + var setProperty = function(object, setter, property, value) { + // Use setter method if present; otherwise, set the property directly. + if (typeof object[setter] === 'function') + object[setter](value); + else + object[property] = value; + } + + describe('InlineResponse20033', function() { + it('should create an instance of InlineResponse20033', function() { + // uncomment below and update the code to test InlineResponse20033 + //var instane = new uclapi.InlineResponse20033(); + //expect(instance).to.be.a(uclapi.InlineResponse20033); + }); + + it('should have the property ok (base name: "ok")', function() { + // uncomment below and update the code to test the property ok + //var instance = new uclapi.InlineResponse20033(); + //expect(instance).to.be(); + }); + + it('should have the property categories (base name: "categories")', function() { + // uncomment below and update the code to test the property categories + //var instance = new uclapi.InlineResponse20033(); + //expect(instance).to.be(); + }); + + }); + +})); diff --git a/test/model/InlineResponse20034.spec.js b/test/model/InlineResponse20034.spec.js new file mode 100644 index 00000000..d3fc41b5 --- /dev/null +++ b/test/model/InlineResponse20034.spec.js @@ -0,0 +1,71 @@ +/** + * UCL API + * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` + * + * The version of the OpenAPI document: 1.4.2 + * Contact: isd.apiteam@ucl.ac.uk + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + * + */ + +(function(root, factory) { + if (typeof define === 'function' && define.amd) { + // AMD. + define(['expect.js', process.cwd()+'/src/index'], factory); + } else if (typeof module === 'object' && module.exports) { + // CommonJS-like environments that support module.exports, like Node. + factory(require('expect.js'), require(process.cwd()+'/src/index')); + } else { + // Browser globals (root is window) + factory(root.expect, root.uclapi); + } +}(this, function(expect, uclapi) { + 'use strict'; + + var instance; + + beforeEach(function() { + instance = new uclapi.InlineResponse20034(); + }); + + var getProperty = function(object, getter, property) { + // Use getter method if present; otherwise, get the property directly. + if (typeof object[getter] === 'function') + return object[getter](); + else + return object[property]; + } + + var setProperty = function(object, setter, property, value) { + // Use setter method if present; otherwise, set the property directly. + if (typeof object[setter] === 'function') + object[setter](value); + else + object[property] = value; + } + + describe('InlineResponse20034', function() { + it('should create an instance of InlineResponse20034', function() { + // uncomment below and update the code to test InlineResponse20034 + //var instane = new uclapi.InlineResponse20034(); + //expect(instance).to.be.a(uclapi.InlineResponse20034); + }); + + it('should have the property ok (base name: "ok")', function() { + // uncomment below and update the code to test the property ok + //var instance = new uclapi.InlineResponse20034(); + //expect(instance).to.be(); + }); + + it('should have the property data (base name: "data")', function() { + // uncomment below and update the code to test the property data + //var instance = new uclapi.InlineResponse20034(); + //expect(instance).to.be(); + }); + + }); + +})); diff --git a/test/model/InlineResponse20035.spec.js b/test/model/InlineResponse20035.spec.js new file mode 100644 index 00000000..7bd79de1 --- /dev/null +++ b/test/model/InlineResponse20035.spec.js @@ -0,0 +1,71 @@ +/** + * UCL API + * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` + * + * The version of the OpenAPI document: 1.4.2 + * Contact: isd.apiteam@ucl.ac.uk + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + * + */ + +(function(root, factory) { + if (typeof define === 'function' && define.amd) { + // AMD. + define(['expect.js', process.cwd()+'/src/index'], factory); + } else if (typeof module === 'object' && module.exports) { + // CommonJS-like environments that support module.exports, like Node. + factory(require('expect.js'), require(process.cwd()+'/src/index')); + } else { + // Browser globals (root is window) + factory(root.expect, root.uclapi); + } +}(this, function(expect, uclapi) { + 'use strict'; + + var instance; + + beforeEach(function() { + instance = new uclapi.InlineResponse20035(); + }); + + var getProperty = function(object, getter, property) { + // Use getter method if present; otherwise, get the property directly. + if (typeof object[getter] === 'function') + return object[getter](); + else + return object[property]; + } + + var setProperty = function(object, setter, property, value) { + // Use setter method if present; otherwise, set the property directly. + if (typeof object[setter] === 'function') + object[setter](value); + else + object[property] = value; + } + + describe('InlineResponse20035', function() { + it('should create an instance of InlineResponse20035', function() { + // uncomment below and update the code to test InlineResponse20035 + //var instane = new uclapi.InlineResponse20035(); + //expect(instance).to.be.a(uclapi.InlineResponse20035); + }); + + it('should have the property ok (base name: "ok")', function() { + // uncomment below and update the code to test the property ok + //var instance = new uclapi.InlineResponse20035(); + //expect(instance).to.be(); + }); + + it('should have the property seats (base name: "seats")', function() { + // uncomment below and update the code to test the property seats + //var instance = new uclapi.InlineResponse20035(); + //expect(instance).to.be(); + }); + + }); + +})); diff --git a/test/model/InlineResponse20036.spec.js b/test/model/InlineResponse20036.spec.js new file mode 100644 index 00000000..ab34fdff --- /dev/null +++ b/test/model/InlineResponse20036.spec.js @@ -0,0 +1,71 @@ +/** + * UCL API + * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` + * + * The version of the OpenAPI document: 1.4.2 + * Contact: isd.apiteam@ucl.ac.uk + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + * + */ + +(function(root, factory) { + if (typeof define === 'function' && define.amd) { + // AMD. + define(['expect.js', process.cwd()+'/src/index'], factory); + } else if (typeof module === 'object' && module.exports) { + // CommonJS-like environments that support module.exports, like Node. + factory(require('expect.js'), require(process.cwd()+'/src/index')); + } else { + // Browser globals (root is window) + factory(root.expect, root.uclapi); + } +}(this, function(expect, uclapi) { + 'use strict'; + + var instance; + + beforeEach(function() { + instance = new uclapi.InlineResponse20036(); + }); + + var getProperty = function(object, getter, property) { + // Use getter method if present; otherwise, get the property directly. + if (typeof object[getter] === 'function') + return object[getter](); + else + return object[property]; + } + + var setProperty = function(object, setter, property, value) { + // Use setter method if present; otherwise, set the property directly. + if (typeof object[setter] === 'function') + object[setter](value); + else + object[property] = value; + } + + describe('InlineResponse20036', function() { + it('should create an instance of InlineResponse20036', function() { + // uncomment below and update the code to test InlineResponse20036 + //var instane = new uclapi.InlineResponse20036(); + //expect(instance).to.be.a(uclapi.InlineResponse20036); + }); + + it('should have the property ok (base name: "ok")', function() { + // uncomment below and update the code to test the property ok + //var instance = new uclapi.InlineResponse20036(); + //expect(instance).to.be(); + }); + + it('should have the property seat (base name: "seat")', function() { + // uncomment below and update the code to test the property seat + //var instance = new uclapi.InlineResponse20036(); + //expect(instance).to.be(); + }); + + }); + +})); diff --git a/test/model/InlineResponse20037.spec.js b/test/model/InlineResponse20037.spec.js new file mode 100644 index 00000000..65a73be4 --- /dev/null +++ b/test/model/InlineResponse20037.spec.js @@ -0,0 +1,71 @@ +/** + * UCL API + * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` + * + * The version of the OpenAPI document: 1.4.2 + * Contact: isd.apiteam@ucl.ac.uk + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + * + */ + +(function(root, factory) { + if (typeof define === 'function' && define.amd) { + // AMD. + define(['expect.js', process.cwd()+'/src/index'], factory); + } else if (typeof module === 'object' && module.exports) { + // CommonJS-like environments that support module.exports, like Node. + factory(require('expect.js'), require(process.cwd()+'/src/index')); + } else { + // Browser globals (root is window) + factory(root.expect, root.uclapi); + } +}(this, function(expect, uclapi) { + 'use strict'; + + var instance; + + beforeEach(function() { + instance = new uclapi.InlineResponse20037(); + }); + + var getProperty = function(object, getter, property) { + // Use getter method if present; otherwise, get the property directly. + if (typeof object[getter] === 'function') + return object[getter](); + else + return object[property]; + } + + var setProperty = function(object, setter, property, value) { + // Use setter method if present; otherwise, set the property directly. + if (typeof object[setter] === 'function') + object[setter](value); + else + object[property] = value; + } + + describe('InlineResponse20037', function() { + it('should create an instance of InlineResponse20037', function() { + // uncomment below and update the code to test InlineResponse20037 + //var instane = new uclapi.InlineResponse20037(); + //expect(instance).to.be.a(uclapi.InlineResponse20037); + }); + + it('should have the property ok (base name: "ok")', function() { + // uncomment below and update the code to test the property ok + //var instance = new uclapi.InlineResponse20037(); + //expect(instance).to.be(); + }); + + it('should have the property zones (base name: "zones")', function() { + // uncomment below and update the code to test the property zones + //var instance = new uclapi.InlineResponse20037(); + //expect(instance).to.be(); + }); + + }); + +})); diff --git a/test/model/InlineResponse20038.spec.js b/test/model/InlineResponse20038.spec.js new file mode 100644 index 00000000..cc78c0c3 --- /dev/null +++ b/test/model/InlineResponse20038.spec.js @@ -0,0 +1,77 @@ +/** + * UCL API + * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` + * + * The version of the OpenAPI document: 1.4.2 + * Contact: isd.apiteam@ucl.ac.uk + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + * + */ + +(function(root, factory) { + if (typeof define === 'function' && define.amd) { + // AMD. + define(['expect.js', process.cwd()+'/src/index'], factory); + } else if (typeof module === 'object' && module.exports) { + // CommonJS-like environments that support module.exports, like Node. + factory(require('expect.js'), require(process.cwd()+'/src/index')); + } else { + // Browser globals (root is window) + factory(root.expect, root.uclapi); + } +}(this, function(expect, uclapi) { + 'use strict'; + + var instance; + + beforeEach(function() { + instance = new uclapi.InlineResponse20038(); + }); + + var getProperty = function(object, getter, property) { + // Use getter method if present; otherwise, get the property directly. + if (typeof object[getter] === 'function') + return object[getter](); + else + return object[property]; + } + + var setProperty = function(object, setter, property, value) { + // Use setter method if present; otherwise, set the property directly. + if (typeof object[setter] === 'function') + object[setter](value); + else + object[property] = value; + } + + describe('InlineResponse20038', function() { + it('should create an instance of InlineResponse20038', function() { + // uncomment below and update the code to test InlineResponse20038 + //var instane = new uclapi.InlineResponse20038(); + //expect(instance).to.be.a(uclapi.InlineResponse20038); + }); + + it('should have the property ok (base name: "ok")', function() { + // uncomment below and update the code to test the property ok + //var instance = new uclapi.InlineResponse20038(); + //expect(instance).to.be(); + }); + + it('should have the property error (base name: "error")', function() { + // uncomment below and update the code to test the property error + //var instance = new uclapi.InlineResponse20038(); + //expect(instance).to.be(); + }); + + it('should have the property zone (base name: "zone")', function() { + // uncomment below and update the code to test the property zone + //var instance = new uclapi.InlineResponse20038(); + //expect(instance).to.be(); + }); + + }); + +})); diff --git a/test/model/InlineResponse20039.spec.js b/test/model/InlineResponse20039.spec.js new file mode 100644 index 00000000..4c3e6fd8 --- /dev/null +++ b/test/model/InlineResponse20039.spec.js @@ -0,0 +1,71 @@ +/** + * UCL API + * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` + * + * The version of the OpenAPI document: 1.4.2 + * Contact: isd.apiteam@ucl.ac.uk + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + * + */ + +(function(root, factory) { + if (typeof define === 'function' && define.amd) { + // AMD. + define(['expect.js', process.cwd()+'/src/index'], factory); + } else if (typeof module === 'object' && module.exports) { + // CommonJS-like environments that support module.exports, like Node. + factory(require('expect.js'), require(process.cwd()+'/src/index')); + } else { + // Browser globals (root is window) + factory(root.expect, root.uclapi); + } +}(this, function(expect, uclapi) { + 'use strict'; + + var instance; + + beforeEach(function() { + instance = new uclapi.InlineResponse20039(); + }); + + var getProperty = function(object, getter, property) { + // Use getter method if present; otherwise, get the property directly. + if (typeof object[getter] === 'function') + return object[getter](); + else + return object[property]; + } + + var setProperty = function(object, setter, property, value) { + // Use setter method if present; otherwise, set the property directly. + if (typeof object[setter] === 'function') + object[setter](value); + else + object[property] = value; + } + + describe('InlineResponse20039', function() { + it('should create an instance of InlineResponse20039', function() { + // uncomment below and update the code to test InlineResponse20039 + //var instane = new uclapi.InlineResponse20039(); + //expect(instance).to.be.a(uclapi.InlineResponse20039); + }); + + it('should have the property ok (base name: "ok")', function() { + // uncomment below and update the code to test the property ok + //var instance = new uclapi.InlineResponse20039(); + //expect(instance).to.be(); + }); + + it('should have the property bookings (base name: "bookings")', function() { + // uncomment below and update the code to test the property bookings + //var instance = new uclapi.InlineResponse20039(); + //expect(instance).to.be(); + }); + + }); + +})); diff --git a/test/model/InlineResponse2004.spec.js b/test/model/InlineResponse2004.spec.js index 3a7d9bf3..b92974ac 100644 --- a/test/model/InlineResponse2004.spec.js +++ b/test/model/InlineResponse2004.spec.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/InlineResponse20040.spec.js b/test/model/InlineResponse20040.spec.js new file mode 100644 index 00000000..a79c84c0 --- /dev/null +++ b/test/model/InlineResponse20040.spec.js @@ -0,0 +1,71 @@ +/** + * UCL API + * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` + * + * The version of the OpenAPI document: 1.4.2 + * Contact: isd.apiteam@ucl.ac.uk + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + * + */ + +(function(root, factory) { + if (typeof define === 'function' && define.amd) { + // AMD. + define(['expect.js', process.cwd()+'/src/index'], factory); + } else if (typeof module === 'object' && module.exports) { + // CommonJS-like environments that support module.exports, like Node. + factory(require('expect.js'), require(process.cwd()+'/src/index')); + } else { + // Browser globals (root is window) + factory(root.expect, root.uclapi); + } +}(this, function(expect, uclapi) { + 'use strict'; + + var instance; + + beforeEach(function() { + instance = new uclapi.InlineResponse20040(); + }); + + var getProperty = function(object, getter, property) { + // Use getter method if present; otherwise, get the property directly. + if (typeof object[getter] === 'function') + return object[getter](); + else + return object[property]; + } + + var setProperty = function(object, setter, property, value) { + // Use setter method if present; otherwise, set the property directly. + if (typeof object[setter] === 'function') + object[setter](value); + else + object[property] = value; + } + + describe('InlineResponse20040', function() { + it('should create an instance of InlineResponse20040', function() { + // uncomment below and update the code to test InlineResponse20040 + //var instane = new uclapi.InlineResponse20040(); + //expect(instance).to.be.a(uclapi.InlineResponse20040); + }); + + it('should have the property ok (base name: "ok")', function() { + // uncomment below and update the code to test the property ok + //var instance = new uclapi.InlineResponse20040(); + //expect(instance).to.be(); + }); + + it('should have the property bookings (base name: "bookings")', function() { + // uncomment below and update the code to test the property bookings + //var instance = new uclapi.InlineResponse20040(); + //expect(instance).to.be(); + }); + + }); + +})); diff --git a/test/model/InlineResponse20041.spec.js b/test/model/InlineResponse20041.spec.js new file mode 100644 index 00000000..ba8a9070 --- /dev/null +++ b/test/model/InlineResponse20041.spec.js @@ -0,0 +1,77 @@ +/** + * UCL API + * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` + * + * The version of the OpenAPI document: 1.4.2 + * Contact: isd.apiteam@ucl.ac.uk + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + * + */ + +(function(root, factory) { + if (typeof define === 'function' && define.amd) { + // AMD. + define(['expect.js', process.cwd()+'/src/index'], factory); + } else if (typeof module === 'object' && module.exports) { + // CommonJS-like environments that support module.exports, like Node. + factory(require('expect.js'), require(process.cwd()+'/src/index')); + } else { + // Browser globals (root is window) + factory(root.expect, root.uclapi); + } +}(this, function(expect, uclapi) { + 'use strict'; + + var instance; + + beforeEach(function() { + instance = new uclapi.InlineResponse20041(); + }); + + var getProperty = function(object, getter, property) { + // Use getter method if present; otherwise, get the property directly. + if (typeof object[getter] === 'function') + return object[getter](); + else + return object[property]; + } + + var setProperty = function(object, setter, property, value) { + // Use setter method if present; otherwise, set the property directly. + if (typeof object[setter] === 'function') + object[setter](value); + else + object[property] = value; + } + + describe('InlineResponse20041', function() { + it('should create an instance of InlineResponse20041', function() { + // uncomment below and update the code to test InlineResponse20041 + //var instane = new uclapi.InlineResponse20041(); + //expect(instance).to.be.a(uclapi.InlineResponse20041); + }); + + it('should have the property ok (base name: "ok")', function() { + // uncomment below and update the code to test the property ok + //var instance = new uclapi.InlineResponse20041(); + //expect(instance).to.be(); + }); + + it('should have the property error (base name: "error")', function() { + // uncomment below and update the code to test the property error + //var instance = new uclapi.InlineResponse20041(); + //expect(instance).to.be(); + }); + + it('should have the property bookings (base name: "bookings")', function() { + // uncomment below and update the code to test the property bookings + //var instance = new uclapi.InlineResponse20041(); + //expect(instance).to.be(); + }); + + }); + +})); diff --git a/test/model/InlineResponse20042.spec.js b/test/model/InlineResponse20042.spec.js new file mode 100644 index 00000000..60f68e3e --- /dev/null +++ b/test/model/InlineResponse20042.spec.js @@ -0,0 +1,71 @@ +/** + * UCL API + * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` + * + * The version of the OpenAPI document: 1.4.2 + * Contact: isd.apiteam@ucl.ac.uk + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + * + */ + +(function(root, factory) { + if (typeof define === 'function' && define.amd) { + // AMD. + define(['expect.js', process.cwd()+'/src/index'], factory); + } else if (typeof module === 'object' && module.exports) { + // CommonJS-like environments that support module.exports, like Node. + factory(require('expect.js'), require(process.cwd()+'/src/index')); + } else { + // Browser globals (root is window) + factory(root.expect, root.uclapi); + } +}(this, function(expect, uclapi) { + 'use strict'; + + var instance; + + beforeEach(function() { + instance = new uclapi.InlineResponse20042(); + }); + + var getProperty = function(object, getter, property) { + // Use getter method if present; otherwise, get the property directly. + if (typeof object[getter] === 'function') + return object[getter](); + else + return object[property]; + } + + var setProperty = function(object, setter, property, value) { + // Use setter method if present; otherwise, set the property directly. + if (typeof object[setter] === 'function') + object[setter](value); + else + object[property] = value; + } + + describe('InlineResponse20042', function() { + it('should create an instance of InlineResponse20042', function() { + // uncomment below and update the code to test InlineResponse20042 + //var instane = new uclapi.InlineResponse20042(); + //expect(instance).to.be.a(uclapi.InlineResponse20042); + }); + + it('should have the property ok (base name: "ok")', function() { + // uncomment below and update the code to test the property ok + //var instance = new uclapi.InlineResponse20042(); + //expect(instance).to.be(); + }); + + it('should have the property bookings (base name: "bookings")', function() { + // uncomment below and update the code to test the property bookings + //var instance = new uclapi.InlineResponse20042(); + //expect(instance).to.be(); + }); + + }); + +})); diff --git a/test/model/InlineResponse2005.spec.js b/test/model/InlineResponse2005.spec.js index 14d70410..cf14bee6 100644 --- a/test/model/InlineResponse2005.spec.js +++ b/test/model/InlineResponse2005.spec.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/InlineResponse2006.spec.js b/test/model/InlineResponse2006.spec.js index 3029c01f..9c38bad0 100644 --- a/test/model/InlineResponse2006.spec.js +++ b/test/model/InlineResponse2006.spec.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/InlineResponse2007.spec.js b/test/model/InlineResponse2007.spec.js index 6e239d4e..2d4d7ee9 100644 --- a/test/model/InlineResponse2007.spec.js +++ b/test/model/InlineResponse2007.spec.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/InlineResponse2008.spec.js b/test/model/InlineResponse2008.spec.js index 6d7c09d8..9f6eb764 100644 --- a/test/model/InlineResponse2008.spec.js +++ b/test/model/InlineResponse2008.spec.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/InlineResponse2009.spec.js b/test/model/InlineResponse2009.spec.js index 153da7e2..8ac31de6 100644 --- a/test/model/InlineResponse2009.spec.js +++ b/test/model/InlineResponse2009.spec.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/Instance.spec.js b/test/model/Instance.spec.js index c209942c..cf959c7c 100644 --- a/test/model/Instance.spec.js +++ b/test/model/Instance.spec.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/Lecturer.spec.js b/test/model/Lecturer.spec.js index 5d8e2811..b0ad5ced 100644 --- a/test/model/Lecturer.spec.js +++ b/test/model/Lecturer.spec.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/LibcalBooking.spec.js b/test/model/LibcalBooking.spec.js new file mode 100644 index 00000000..b50989fe --- /dev/null +++ b/test/model/LibcalBooking.spec.js @@ -0,0 +1,89 @@ +/** + * UCL API + * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` + * + * The version of the OpenAPI document: 1.4.2 + * Contact: isd.apiteam@ucl.ac.uk + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + * + */ + +(function(root, factory) { + if (typeof define === 'function' && define.amd) { + // AMD. + define(['expect.js', process.cwd()+'/src/index'], factory); + } else if (typeof module === 'object' && module.exports) { + // CommonJS-like environments that support module.exports, like Node. + factory(require('expect.js'), require(process.cwd()+'/src/index')); + } else { + // Browser globals (root is window) + factory(root.expect, root.uclapi); + } +}(this, function(expect, uclapi) { + 'use strict'; + + var instance; + + beforeEach(function() { + instance = new uclapi.LibcalBooking(); + }); + + var getProperty = function(object, getter, property) { + // Use getter method if present; otherwise, get the property directly. + if (typeof object[getter] === 'function') + return object[getter](); + else + return object[property]; + } + + var setProperty = function(object, setter, property, value) { + // Use setter method if present; otherwise, set the property directly. + if (typeof object[setter] === 'function') + object[setter](value); + else + object[property] = value; + } + + describe('LibcalBooking', function() { + it('should create an instance of LibcalBooking', function() { + // uncomment below and update the code to test LibcalBooking + //var instane = new uclapi.LibcalBooking(); + //expect(instance).to.be.a(uclapi.LibcalBooking); + }); + + it('should have the property nickname (base name: "nickname")', function() { + // uncomment below and update the code to test the property nickname + //var instance = new uclapi.LibcalBooking(); + //expect(instance).to.be(); + }); + + it('should have the property start (base name: "start")', function() { + // uncomment below and update the code to test the property start + //var instance = new uclapi.LibcalBooking(); + //expect(instance).to.be(); + }); + + it('should have the property end (base name: "end")', function() { + // uncomment below and update the code to test the property end + //var instance = new uclapi.LibcalBooking(); + //expect(instance).to.be(); + }); + + it('should have the property created (base name: "created")', function() { + // uncomment below and update the code to test the property created + //var instance = new uclapi.LibcalBooking(); + //expect(instance).to.be(); + }); + + it('should have the property bookingId (base name: "booking_id")', function() { + // uncomment below and update the code to test the property bookingId + //var instance = new uclapi.LibcalBooking(); + //expect(instance).to.be(); + }); + + }); + +})); diff --git a/test/model/LibcalCategory.spec.js b/test/model/LibcalCategory.spec.js new file mode 100644 index 00000000..54d2ce9a --- /dev/null +++ b/test/model/LibcalCategory.spec.js @@ -0,0 +1,83 @@ +/** + * UCL API + * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` + * + * The version of the OpenAPI document: 1.4.2 + * Contact: isd.apiteam@ucl.ac.uk + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + * + */ + +(function(root, factory) { + if (typeof define === 'function' && define.amd) { + // AMD. + define(['expect.js', process.cwd()+'/src/index'], factory); + } else if (typeof module === 'object' && module.exports) { + // CommonJS-like environments that support module.exports, like Node. + factory(require('expect.js'), require(process.cwd()+'/src/index')); + } else { + // Browser globals (root is window) + factory(root.expect, root.uclapi); + } +}(this, function(expect, uclapi) { + 'use strict'; + + var instance; + + beforeEach(function() { + instance = new uclapi.LibcalCategory(); + }); + + var getProperty = function(object, getter, property) { + // Use getter method if present; otherwise, get the property directly. + if (typeof object[getter] === 'function') + return object[getter](); + else + return object[property]; + } + + var setProperty = function(object, setter, property, value) { + // Use setter method if present; otherwise, set the property directly. + if (typeof object[setter] === 'function') + object[setter](value); + else + object[property] = value; + } + + describe('LibcalCategory', function() { + it('should create an instance of LibcalCategory', function() { + // uncomment below and update the code to test LibcalCategory + //var instane = new uclapi.LibcalCategory(); + //expect(instance).to.be.a(uclapi.LibcalCategory); + }); + + it('should have the property cid (base name: "cid")', function() { + // uncomment below and update the code to test the property cid + //var instance = new uclapi.LibcalCategory(); + //expect(instance).to.be(); + }); + + it('should have the property formid (base name: "formid")', function() { + // uncomment below and update the code to test the property formid + //var instance = new uclapi.LibcalCategory(); + //expect(instance).to.be(); + }); + + it('should have the property name (base name: "name")', function() { + // uncomment below and update the code to test the property name + //var instance = new uclapi.LibcalCategory(); + //expect(instance).to.be(); + }); + + it('should have the property _public (base name: "public")', function() { + // uncomment below and update the code to test the property _public + //var instance = new uclapi.LibcalCategory(); + //expect(instance).to.be(); + }); + + }); + +})); diff --git a/test/model/LibcalForm.spec.js b/test/model/LibcalForm.spec.js new file mode 100644 index 00000000..34e346f3 --- /dev/null +++ b/test/model/LibcalForm.spec.js @@ -0,0 +1,77 @@ +/** + * UCL API + * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` + * + * The version of the OpenAPI document: 1.4.2 + * Contact: isd.apiteam@ucl.ac.uk + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + * + */ + +(function(root, factory) { + if (typeof define === 'function' && define.amd) { + // AMD. + define(['expect.js', process.cwd()+'/src/index'], factory); + } else if (typeof module === 'object' && module.exports) { + // CommonJS-like environments that support module.exports, like Node. + factory(require('expect.js'), require(process.cwd()+'/src/index')); + } else { + // Browser globals (root is window) + factory(root.expect, root.uclapi); + } +}(this, function(expect, uclapi) { + 'use strict'; + + var instance; + + beforeEach(function() { + instance = new uclapi.LibcalForm(); + }); + + var getProperty = function(object, getter, property) { + // Use getter method if present; otherwise, get the property directly. + if (typeof object[getter] === 'function') + return object[getter](); + else + return object[property]; + } + + var setProperty = function(object, setter, property, value) { + // Use setter method if present; otherwise, set the property directly. + if (typeof object[setter] === 'function') + object[setter](value); + else + object[property] = value; + } + + describe('LibcalForm', function() { + it('should create an instance of LibcalForm', function() { + // uncomment below and update the code to test LibcalForm + //var instane = new uclapi.LibcalForm(); + //expect(instance).to.be.a(uclapi.LibcalForm); + }); + + it('should have the property id (base name: "id")', function() { + // uncomment below and update the code to test the property id + //var instance = new uclapi.LibcalForm(); + //expect(instance).to.be(); + }); + + it('should have the property name (base name: "name")', function() { + // uncomment below and update the code to test the property name + //var instance = new uclapi.LibcalForm(); + //expect(instance).to.be(); + }); + + it('should have the property fields (base name: "fields")', function() { + // uncomment below and update the code to test the property fields + //var instance = new uclapi.LibcalForm(); + //expect(instance).to.be(); + }); + + }); + +})); diff --git a/test/model/LibcalFormField.spec.js b/test/model/LibcalFormField.spec.js new file mode 100644 index 00000000..43fff8ad --- /dev/null +++ b/test/model/LibcalFormField.spec.js @@ -0,0 +1,83 @@ +/** + * UCL API + * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` + * + * The version of the OpenAPI document: 1.4.2 + * Contact: isd.apiteam@ucl.ac.uk + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + * + */ + +(function(root, factory) { + if (typeof define === 'function' && define.amd) { + // AMD. + define(['expect.js', process.cwd()+'/src/index'], factory); + } else if (typeof module === 'object' && module.exports) { + // CommonJS-like environments that support module.exports, like Node. + factory(require('expect.js'), require(process.cwd()+'/src/index')); + } else { + // Browser globals (root is window) + factory(root.expect, root.uclapi); + } +}(this, function(expect, uclapi) { + 'use strict'; + + var instance; + + beforeEach(function() { + instance = new uclapi.LibcalFormField(); + }); + + var getProperty = function(object, getter, property) { + // Use getter method if present; otherwise, get the property directly. + if (typeof object[getter] === 'function') + return object[getter](); + else + return object[property]; + } + + var setProperty = function(object, setter, property, value) { + // Use setter method if present; otherwise, set the property directly. + if (typeof object[setter] === 'function') + object[setter](value); + else + object[property] = value; + } + + describe('LibcalFormField', function() { + it('should create an instance of LibcalFormField', function() { + // uncomment below and update the code to test LibcalFormField + //var instane = new uclapi.LibcalFormField(); + //expect(instance).to.be.a(uclapi.LibcalFormField); + }); + + it('should have the property label (base name: "label")', function() { + // uncomment below and update the code to test the property label + //var instance = new uclapi.LibcalFormField(); + //expect(instance).to.be(); + }); + + it('should have the property type (base name: "type")', function() { + // uncomment below and update the code to test the property type + //var instance = new uclapi.LibcalFormField(); + //expect(instance).to.be(); + }); + + it('should have the property required (base name: "required")', function() { + // uncomment below and update the code to test the property required + //var instance = new uclapi.LibcalFormField(); + //expect(instance).to.be(); + }); + + it('should have the property options (base name: "options")', function() { + // uncomment below and update the code to test the property options + //var instance = new uclapi.LibcalFormField(); + //expect(instance).to.be(); + }); + + }); + +})); diff --git a/test/model/LibcalLocation.spec.js b/test/model/LibcalLocation.spec.js new file mode 100644 index 00000000..66d69535 --- /dev/null +++ b/test/model/LibcalLocation.spec.js @@ -0,0 +1,83 @@ +/** + * UCL API + * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` + * + * The version of the OpenAPI document: 1.4.2 + * Contact: isd.apiteam@ucl.ac.uk + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + * + */ + +(function(root, factory) { + if (typeof define === 'function' && define.amd) { + // AMD. + define(['expect.js', process.cwd()+'/src/index'], factory); + } else if (typeof module === 'object' && module.exports) { + // CommonJS-like environments that support module.exports, like Node. + factory(require('expect.js'), require(process.cwd()+'/src/index')); + } else { + // Browser globals (root is window) + factory(root.expect, root.uclapi); + } +}(this, function(expect, uclapi) { + 'use strict'; + + var instance; + + beforeEach(function() { + instance = new uclapi.LibcalLocation(); + }); + + var getProperty = function(object, getter, property) { + // Use getter method if present; otherwise, get the property directly. + if (typeof object[getter] === 'function') + return object[getter](); + else + return object[property]; + } + + var setProperty = function(object, setter, property, value) { + // Use setter method if present; otherwise, set the property directly. + if (typeof object[setter] === 'function') + object[setter](value); + else + object[property] = value; + } + + describe('LibcalLocation', function() { + it('should create an instance of LibcalLocation', function() { + // uncomment below and update the code to test LibcalLocation + //var instane = new uclapi.LibcalLocation(); + //expect(instance).to.be.a(uclapi.LibcalLocation); + }); + + it('should have the property _public (base name: "public")', function() { + // uncomment below and update the code to test the property _public + //var instance = new uclapi.LibcalLocation(); + //expect(instance).to.be(); + }); + + it('should have the property terms (base name: "terms")', function() { + // uncomment below and update the code to test the property terms + //var instance = new uclapi.LibcalLocation(); + //expect(instance).to.be(); + }); + + it('should have the property lid (base name: "lid")', function() { + // uncomment below and update the code to test the property lid + //var instance = new uclapi.LibcalLocation(); + //expect(instance).to.be(); + }); + + it('should have the property name (base name: "name")', function() { + // uncomment below and update the code to test the property name + //var instance = new uclapi.LibcalLocation(); + //expect(instance).to.be(); + }); + + }); + +})); diff --git a/test/model/LibcalLocationBase.spec.js b/test/model/LibcalLocationBase.spec.js new file mode 100644 index 00000000..1360e85e --- /dev/null +++ b/test/model/LibcalLocationBase.spec.js @@ -0,0 +1,71 @@ +/** + * UCL API + * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` + * + * The version of the OpenAPI document: 1.4.2 + * Contact: isd.apiteam@ucl.ac.uk + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + * + */ + +(function(root, factory) { + if (typeof define === 'function' && define.amd) { + // AMD. + define(['expect.js', process.cwd()+'/src/index'], factory); + } else if (typeof module === 'object' && module.exports) { + // CommonJS-like environments that support module.exports, like Node. + factory(require('expect.js'), require(process.cwd()+'/src/index')); + } else { + // Browser globals (root is window) + factory(root.expect, root.uclapi); + } +}(this, function(expect, uclapi) { + 'use strict'; + + var instance; + + beforeEach(function() { + instance = new uclapi.LibcalLocationBase(); + }); + + var getProperty = function(object, getter, property) { + // Use getter method if present; otherwise, get the property directly. + if (typeof object[getter] === 'function') + return object[getter](); + else + return object[property]; + } + + var setProperty = function(object, setter, property, value) { + // Use setter method if present; otherwise, set the property directly. + if (typeof object[setter] === 'function') + object[setter](value); + else + object[property] = value; + } + + describe('LibcalLocationBase', function() { + it('should create an instance of LibcalLocationBase', function() { + // uncomment below and update the code to test LibcalLocationBase + //var instane = new uclapi.LibcalLocationBase(); + //expect(instance).to.be.a(uclapi.LibcalLocationBase); + }); + + it('should have the property lid (base name: "lid")', function() { + // uncomment below and update the code to test the property lid + //var instance = new uclapi.LibcalLocationBase(); + //expect(instance).to.be(); + }); + + it('should have the property name (base name: "name")', function() { + // uncomment below and update the code to test the property name + //var instance = new uclapi.LibcalLocationBase(); + //expect(instance).to.be(); + }); + + }); + +})); diff --git a/test/model/LibcalPersonalSeatBooking.spec.js b/test/model/LibcalPersonalSeatBooking.spec.js new file mode 100644 index 00000000..728ab9a7 --- /dev/null +++ b/test/model/LibcalPersonalSeatBooking.spec.js @@ -0,0 +1,167 @@ +/** + * UCL API + * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` + * + * The version of the OpenAPI document: 1.4.2 + * Contact: isd.apiteam@ucl.ac.uk + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + * + */ + +(function(root, factory) { + if (typeof define === 'function' && define.amd) { + // AMD. + define(['expect.js', process.cwd()+'/src/index'], factory); + } else if (typeof module === 'object' && module.exports) { + // CommonJS-like environments that support module.exports, like Node. + factory(require('expect.js'), require(process.cwd()+'/src/index')); + } else { + // Browser globals (root is window) + factory(root.expect, root.uclapi); + } +}(this, function(expect, uclapi) { + 'use strict'; + + var instance; + + beforeEach(function() { + instance = new uclapi.LibcalPersonalSeatBooking(); + }); + + var getProperty = function(object, getter, property) { + // Use getter method if present; otherwise, get the property directly. + if (typeof object[getter] === 'function') + return object[getter](); + else + return object[property]; + } + + var setProperty = function(object, setter, property, value) { + // Use setter method if present; otherwise, set the property directly. + if (typeof object[setter] === 'function') + object[setter](value); + else + object[property] = value; + } + + describe('LibcalPersonalSeatBooking', function() { + it('should create an instance of LibcalPersonalSeatBooking', function() { + // uncomment below and update the code to test LibcalPersonalSeatBooking + //var instane = new uclapi.LibcalPersonalSeatBooking(); + //expect(instance).to.be.a(uclapi.LibcalPersonalSeatBooking); + }); + + it('should have the property bookId (base name: "book_id")', function() { + // uncomment below and update the code to test the property bookId + //var instance = new uclapi.LibcalPersonalSeatBooking(); + //expect(instance).to.be(); + }); + + it('should have the property firstName (base name: "first_name")', function() { + // uncomment below and update the code to test the property firstName + //var instance = new uclapi.LibcalPersonalSeatBooking(); + //expect(instance).to.be(); + }); + + it('should have the property lastName (base name: "last_name")', function() { + // uncomment below and update the code to test the property lastName + //var instance = new uclapi.LibcalPersonalSeatBooking(); + //expect(instance).to.be(); + }); + + it('should have the property email (base name: "email")', function() { + // uncomment below and update the code to test the property email + //var instance = new uclapi.LibcalPersonalSeatBooking(); + //expect(instance).to.be(); + }); + + it('should have the property checkInCode (base name: "check_in_code")', function() { + // uncomment below and update the code to test the property checkInCode + //var instance = new uclapi.LibcalPersonalSeatBooking(); + //expect(instance).to.be(); + }); + + it('should have the property eid (base name: "eid")', function() { + // uncomment below and update the code to test the property eid + //var instance = new uclapi.LibcalPersonalSeatBooking(); + //expect(instance).to.be(); + }); + + it('should have the property cid (base name: "cid")', function() { + // uncomment below and update the code to test the property cid + //var instance = new uclapi.LibcalPersonalSeatBooking(); + //expect(instance).to.be(); + }); + + it('should have the property lid (base name: "lid")', function() { + // uncomment below and update the code to test the property lid + //var instance = new uclapi.LibcalPersonalSeatBooking(); + //expect(instance).to.be(); + }); + + it('should have the property fromDate (base name: "from_date")', function() { + // uncomment below and update the code to test the property fromDate + //var instance = new uclapi.LibcalPersonalSeatBooking(); + //expect(instance).to.be(); + }); + + it('should have the property toDate (base name: "to_date")', function() { + // uncomment below and update the code to test the property toDate + //var instance = new uclapi.LibcalPersonalSeatBooking(); + //expect(instance).to.be(); + }); + + it('should have the property created (base name: "created")', function() { + // uncomment below and update the code to test the property created + //var instance = new uclapi.LibcalPersonalSeatBooking(); + //expect(instance).to.be(); + }); + + it('should have the property status (base name: "status")', function() { + // uncomment below and update the code to test the property status + //var instance = new uclapi.LibcalPersonalSeatBooking(); + //expect(instance).to.be(); + }); + + it('should have the property locationName (base name: "location_name")', function() { + // uncomment below and update the code to test the property locationName + //var instance = new uclapi.LibcalPersonalSeatBooking(); + //expect(instance).to.be(); + }); + + it('should have the property categoryName (base name: "category_name")', function() { + // uncomment below and update the code to test the property categoryName + //var instance = new uclapi.LibcalPersonalSeatBooking(); + //expect(instance).to.be(); + }); + + it('should have the property itemName (base name: "item_name")', function() { + // uncomment below and update the code to test the property itemName + //var instance = new uclapi.LibcalPersonalSeatBooking(); + //expect(instance).to.be(); + }); + + it('should have the property seatId (base name: "seat_id")', function() { + // uncomment below and update the code to test the property seatId + //var instance = new uclapi.LibcalPersonalSeatBooking(); + //expect(instance).to.be(); + }); + + it('should have the property seatName (base name: "seat_name")', function() { + // uncomment below and update the code to test the property seatName + //var instance = new uclapi.LibcalPersonalSeatBooking(); + //expect(instance).to.be(); + }); + + it('should have the property cancelled (base name: "cancelled")', function() { + // uncomment below and update the code to test the property cancelled + //var instance = new uclapi.LibcalPersonalSeatBooking(); + //expect(instance).to.be(); + }); + + }); + +})); diff --git a/test/model/LibcalReserveRequest.spec.js b/test/model/LibcalReserveRequest.spec.js new file mode 100644 index 00000000..27d3157d --- /dev/null +++ b/test/model/LibcalReserveRequest.spec.js @@ -0,0 +1,83 @@ +/** + * UCL API + * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` + * + * The version of the OpenAPI document: 1.4.2 + * Contact: isd.apiteam@ucl.ac.uk + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + * + */ + +(function(root, factory) { + if (typeof define === 'function' && define.amd) { + // AMD. + define(['expect.js', process.cwd()+'/src/index'], factory); + } else if (typeof module === 'object' && module.exports) { + // CommonJS-like environments that support module.exports, like Node. + factory(require('expect.js'), require(process.cwd()+'/src/index')); + } else { + // Browser globals (root is window) + factory(root.expect, root.uclapi); + } +}(this, function(expect, uclapi) { + 'use strict'; + + var instance; + + beforeEach(function() { + instance = new uclapi.LibcalReserveRequest(); + }); + + var getProperty = function(object, getter, property) { + // Use getter method if present; otherwise, get the property directly. + if (typeof object[getter] === 'function') + return object[getter](); + else + return object[property]; + } + + var setProperty = function(object, setter, property, value) { + // Use setter method if present; otherwise, set the property directly. + if (typeof object[setter] === 'function') + object[setter](value); + else + object[property] = value; + } + + describe('LibcalReserveRequest', function() { + it('should create an instance of LibcalReserveRequest', function() { + // uncomment below and update the code to test LibcalReserveRequest + //var instane = new uclapi.LibcalReserveRequest(); + //expect(instance).to.be.a(uclapi.LibcalReserveRequest); + }); + + it('should have the property start (base name: "start")', function() { + // uncomment below and update the code to test the property start + //var instance = new uclapi.LibcalReserveRequest(); + //expect(instance).to.be(); + }); + + it('should have the property test (base name: "test")', function() { + // uncomment below and update the code to test the property test + //var instance = new uclapi.LibcalReserveRequest(); + //expect(instance).to.be(); + }); + + it('should have the property nickname (base name: "nickname")', function() { + // uncomment below and update the code to test the property nickname + //var instance = new uclapi.LibcalReserveRequest(); + //expect(instance).to.be(); + }); + + it('should have the property bookings (base name: "bookings")', function() { + // uncomment below and update the code to test the property bookings + //var instance = new uclapi.LibcalReserveRequest(); + //expect(instance).to.be(); + }); + + }); + +})); diff --git a/test/model/LibcalReserveRequestBooking.spec.js b/test/model/LibcalReserveRequestBooking.spec.js new file mode 100644 index 00000000..e5a74ddf --- /dev/null +++ b/test/model/LibcalReserveRequestBooking.spec.js @@ -0,0 +1,77 @@ +/** + * UCL API + * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` + * + * The version of the OpenAPI document: 1.4.2 + * Contact: isd.apiteam@ucl.ac.uk + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + * + */ + +(function(root, factory) { + if (typeof define === 'function' && define.amd) { + // AMD. + define(['expect.js', process.cwd()+'/src/index'], factory); + } else if (typeof module === 'object' && module.exports) { + // CommonJS-like environments that support module.exports, like Node. + factory(require('expect.js'), require(process.cwd()+'/src/index')); + } else { + // Browser globals (root is window) + factory(root.expect, root.uclapi); + } +}(this, function(expect, uclapi) { + 'use strict'; + + var instance; + + beforeEach(function() { + instance = new uclapi.LibcalReserveRequestBooking(); + }); + + var getProperty = function(object, getter, property) { + // Use getter method if present; otherwise, get the property directly. + if (typeof object[getter] === 'function') + return object[getter](); + else + return object[property]; + } + + var setProperty = function(object, setter, property, value) { + // Use setter method if present; otherwise, set the property directly. + if (typeof object[setter] === 'function') + object[setter](value); + else + object[property] = value; + } + + describe('LibcalReserveRequestBooking', function() { + it('should create an instance of LibcalReserveRequestBooking', function() { + // uncomment below and update the code to test LibcalReserveRequestBooking + //var instane = new uclapi.LibcalReserveRequestBooking(); + //expect(instance).to.be.a(uclapi.LibcalReserveRequestBooking); + }); + + it('should have the property id (base name: "id")', function() { + // uncomment below and update the code to test the property id + //var instance = new uclapi.LibcalReserveRequestBooking(); + //expect(instance).to.be(); + }); + + it('should have the property to (base name: "to")', function() { + // uncomment below and update the code to test the property to + //var instance = new uclapi.LibcalReserveRequestBooking(); + //expect(instance).to.be(); + }); + + it('should have the property seatId (base name: "seat_id")', function() { + // uncomment below and update the code to test the property seatId + //var instance = new uclapi.LibcalReserveRequestBooking(); + //expect(instance).to.be(); + }); + + }); + +})); diff --git a/test/model/LibcalSeat.spec.js b/test/model/LibcalSeat.spec.js new file mode 100644 index 00000000..f4222156 --- /dev/null +++ b/test/model/LibcalSeat.spec.js @@ -0,0 +1,101 @@ +/** + * UCL API + * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` + * + * The version of the OpenAPI document: 1.4.2 + * Contact: isd.apiteam@ucl.ac.uk + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + * + */ + +(function(root, factory) { + if (typeof define === 'function' && define.amd) { + // AMD. + define(['expect.js', process.cwd()+'/src/index'], factory); + } else if (typeof module === 'object' && module.exports) { + // CommonJS-like environments that support module.exports, like Node. + factory(require('expect.js'), require(process.cwd()+'/src/index')); + } else { + // Browser globals (root is window) + factory(root.expect, root.uclapi); + } +}(this, function(expect, uclapi) { + 'use strict'; + + var instance; + + beforeEach(function() { + instance = new uclapi.LibcalSeat(); + }); + + var getProperty = function(object, getter, property) { + // Use getter method if present; otherwise, get the property directly. + if (typeof object[getter] === 'function') + return object[getter](); + else + return object[property]; + } + + var setProperty = function(object, setter, property, value) { + // Use setter method if present; otherwise, set the property directly. + if (typeof object[setter] === 'function') + object[setter](value); + else + object[property] = value; + } + + describe('LibcalSeat', function() { + it('should create an instance of LibcalSeat', function() { + // uncomment below and update the code to test LibcalSeat + //var instane = new uclapi.LibcalSeat(); + //expect(instance).to.be.a(uclapi.LibcalSeat); + }); + + it('should have the property id (base name: "id")', function() { + // uncomment below and update the code to test the property id + //var instance = new uclapi.LibcalSeat(); + //expect(instance).to.be(); + }); + + it('should have the property name (base name: "name")', function() { + // uncomment below and update the code to test the property name + //var instance = new uclapi.LibcalSeat(); + //expect(instance).to.be(); + }); + + it('should have the property description (base name: "description")', function() { + // uncomment below and update the code to test the property description + //var instance = new uclapi.LibcalSeat(); + //expect(instance).to.be(); + }); + + it('should have the property isAccessible (base name: "is_accessible")', function() { + // uncomment below and update the code to test the property isAccessible + //var instance = new uclapi.LibcalSeat(); + //expect(instance).to.be(); + }); + + it('should have the property isPowered (base name: "is_powered")', function() { + // uncomment below and update the code to test the property isPowered + //var instance = new uclapi.LibcalSeat(); + //expect(instance).to.be(); + }); + + it('should have the property image (base name: "image")', function() { + // uncomment below and update the code to test the property image + //var instance = new uclapi.LibcalSeat(); + //expect(instance).to.be(); + }); + + it('should have the property status (base name: "status")', function() { + // uncomment below and update the code to test the property status + //var instance = new uclapi.LibcalSeat(); + //expect(instance).to.be(); + }); + + }); + +})); diff --git a/test/model/LibcalSeatBooking.spec.js b/test/model/LibcalSeatBooking.spec.js new file mode 100644 index 00000000..9e115b01 --- /dev/null +++ b/test/model/LibcalSeatBooking.spec.js @@ -0,0 +1,137 @@ +/** + * UCL API + * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` + * + * The version of the OpenAPI document: 1.4.2 + * Contact: isd.apiteam@ucl.ac.uk + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + * + */ + +(function(root, factory) { + if (typeof define === 'function' && define.amd) { + // AMD. + define(['expect.js', process.cwd()+'/src/index'], factory); + } else if (typeof module === 'object' && module.exports) { + // CommonJS-like environments that support module.exports, like Node. + factory(require('expect.js'), require(process.cwd()+'/src/index')); + } else { + // Browser globals (root is window) + factory(root.expect, root.uclapi); + } +}(this, function(expect, uclapi) { + 'use strict'; + + var instance; + + beforeEach(function() { + instance = new uclapi.LibcalSeatBooking(); + }); + + var getProperty = function(object, getter, property) { + // Use getter method if present; otherwise, get the property directly. + if (typeof object[getter] === 'function') + return object[getter](); + else + return object[property]; + } + + var setProperty = function(object, setter, property, value) { + // Use setter method if present; otherwise, set the property directly. + if (typeof object[setter] === 'function') + object[setter](value); + else + object[property] = value; + } + + describe('LibcalSeatBooking', function() { + it('should create an instance of LibcalSeatBooking', function() { + // uncomment below and update the code to test LibcalSeatBooking + //var instane = new uclapi.LibcalSeatBooking(); + //expect(instance).to.be.a(uclapi.LibcalSeatBooking); + }); + + it('should have the property eid (base name: "eid")', function() { + // uncomment below and update the code to test the property eid + //var instance = new uclapi.LibcalSeatBooking(); + //expect(instance).to.be(); + }); + + it('should have the property cid (base name: "cid")', function() { + // uncomment below and update the code to test the property cid + //var instance = new uclapi.LibcalSeatBooking(); + //expect(instance).to.be(); + }); + + it('should have the property lid (base name: "lid")', function() { + // uncomment below and update the code to test the property lid + //var instance = new uclapi.LibcalSeatBooking(); + //expect(instance).to.be(); + }); + + it('should have the property fromDate (base name: "from_date")', function() { + // uncomment below and update the code to test the property fromDate + //var instance = new uclapi.LibcalSeatBooking(); + //expect(instance).to.be(); + }); + + it('should have the property toDate (base name: "to_date")', function() { + // uncomment below and update the code to test the property toDate + //var instance = new uclapi.LibcalSeatBooking(); + //expect(instance).to.be(); + }); + + it('should have the property created (base name: "created")', function() { + // uncomment below and update the code to test the property created + //var instance = new uclapi.LibcalSeatBooking(); + //expect(instance).to.be(); + }); + + it('should have the property status (base name: "status")', function() { + // uncomment below and update the code to test the property status + //var instance = new uclapi.LibcalSeatBooking(); + //expect(instance).to.be(); + }); + + it('should have the property locationName (base name: "location_name")', function() { + // uncomment below and update the code to test the property locationName + //var instance = new uclapi.LibcalSeatBooking(); + //expect(instance).to.be(); + }); + + it('should have the property categoryName (base name: "category_name")', function() { + // uncomment below and update the code to test the property categoryName + //var instance = new uclapi.LibcalSeatBooking(); + //expect(instance).to.be(); + }); + + it('should have the property itemName (base name: "item_name")', function() { + // uncomment below and update the code to test the property itemName + //var instance = new uclapi.LibcalSeatBooking(); + //expect(instance).to.be(); + }); + + it('should have the property seatId (base name: "seat_id")', function() { + // uncomment below and update the code to test the property seatId + //var instance = new uclapi.LibcalSeatBooking(); + //expect(instance).to.be(); + }); + + it('should have the property seatName (base name: "seat_name")', function() { + // uncomment below and update the code to test the property seatName + //var instance = new uclapi.LibcalSeatBooking(); + //expect(instance).to.be(); + }); + + it('should have the property cancelled (base name: "cancelled")', function() { + // uncomment below and update the code to test the property cancelled + //var instance = new uclapi.LibcalSeatBooking(); + //expect(instance).to.be(); + }); + + }); + +})); diff --git a/test/model/LibcalSpaceBase.spec.js b/test/model/LibcalSpaceBase.spec.js new file mode 100644 index 00000000..c137585b --- /dev/null +++ b/test/model/LibcalSpaceBase.spec.js @@ -0,0 +1,95 @@ +/** + * UCL API + * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` + * + * The version of the OpenAPI document: 1.4.2 + * Contact: isd.apiteam@ucl.ac.uk + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + * + */ + +(function(root, factory) { + if (typeof define === 'function' && define.amd) { + // AMD. + define(['expect.js', process.cwd()+'/src/index'], factory); + } else if (typeof module === 'object' && module.exports) { + // CommonJS-like environments that support module.exports, like Node. + factory(require('expect.js'), require(process.cwd()+'/src/index')); + } else { + // Browser globals (root is window) + factory(root.expect, root.uclapi); + } +}(this, function(expect, uclapi) { + 'use strict'; + + var instance; + + beforeEach(function() { + instance = new uclapi.LibcalSpaceBase(); + }); + + var getProperty = function(object, getter, property) { + // Use getter method if present; otherwise, get the property directly. + if (typeof object[getter] === 'function') + return object[getter](); + else + return object[property]; + } + + var setProperty = function(object, setter, property, value) { + // Use setter method if present; otherwise, set the property directly. + if (typeof object[setter] === 'function') + object[setter](value); + else + object[property] = value; + } + + describe('LibcalSpaceBase', function() { + it('should create an instance of LibcalSpaceBase', function() { + // uncomment below and update the code to test LibcalSpaceBase + //var instane = new uclapi.LibcalSpaceBase(); + //expect(instance).to.be.a(uclapi.LibcalSpaceBase); + }); + + it('should have the property id (base name: "id")', function() { + // uncomment below and update the code to test the property id + //var instance = new uclapi.LibcalSpaceBase(); + //expect(instance).to.be(); + }); + + it('should have the property name (base name: "name")', function() { + // uncomment below and update the code to test the property name + //var instance = new uclapi.LibcalSpaceBase(); + //expect(instance).to.be(); + }); + + it('should have the property description (base name: "description")', function() { + // uncomment below and update the code to test the property description + //var instance = new uclapi.LibcalSpaceBase(); + //expect(instance).to.be(); + }); + + it('should have the property image (base name: "image")', function() { + // uncomment below and update the code to test the property image + //var instance = new uclapi.LibcalSpaceBase(); + //expect(instance).to.be(); + }); + + it('should have the property capacity (base name: "capacity")', function() { + // uncomment below and update the code to test the property capacity + //var instance = new uclapi.LibcalSpaceBase(); + //expect(instance).to.be(); + }); + + it('should have the property formid (base name: "formid")', function() { + // uncomment below and update the code to test the property formid + //var instance = new uclapi.LibcalSpaceBase(); + //expect(instance).to.be(); + }); + + }); + +})); diff --git a/test/model/LibcalUtilisationSeatSummary.spec.js b/test/model/LibcalUtilisationSeatSummary.spec.js new file mode 100644 index 00000000..1abc44cf --- /dev/null +++ b/test/model/LibcalUtilisationSeatSummary.spec.js @@ -0,0 +1,77 @@ +/** + * UCL API + * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` + * + * The version of the OpenAPI document: 1.4.2 + * Contact: isd.apiteam@ucl.ac.uk + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + * + */ + +(function(root, factory) { + if (typeof define === 'function' && define.amd) { + // AMD. + define(['expect.js', process.cwd()+'/src/index'], factory); + } else if (typeof module === 'object' && module.exports) { + // CommonJS-like environments that support module.exports, like Node. + factory(require('expect.js'), require(process.cwd()+'/src/index')); + } else { + // Browser globals (root is window) + factory(root.expect, root.uclapi); + } +}(this, function(expect, uclapi) { + 'use strict'; + + var instance; + + beforeEach(function() { + instance = new uclapi.LibcalUtilisationSeatSummary(); + }); + + var getProperty = function(object, getter, property) { + // Use getter method if present; otherwise, get the property directly. + if (typeof object[getter] === 'function') + return object[getter](); + else + return object[property]; + } + + var setProperty = function(object, setter, property, value) { + // Use setter method if present; otherwise, set the property directly. + if (typeof object[setter] === 'function') + object[setter](value); + else + object[property] = value; + } + + describe('LibcalUtilisationSeatSummary', function() { + it('should create an instance of LibcalUtilisationSeatSummary', function() { + // uncomment below and update the code to test LibcalUtilisationSeatSummary + //var instane = new uclapi.LibcalUtilisationSeatSummary(); + //expect(instance).to.be.a(uclapi.LibcalUtilisationSeatSummary); + }); + + it('should have the property active (base name: "active")', function() { + // uncomment below and update the code to test the property active + //var instance = new uclapi.LibcalUtilisationSeatSummary(); + //expect(instance).to.be(); + }); + + it('should have the property bookableCount (base name: "bookable_count")', function() { + // uncomment below and update the code to test the property bookableCount + //var instance = new uclapi.LibcalUtilisationSeatSummary(); + //expect(instance).to.be(); + }); + + it('should have the property total (base name: "total")', function() { + // uncomment below and update the code to test the property total + //var instance = new uclapi.LibcalUtilisationSeatSummary(); + //expect(instance).to.be(); + }); + + }); + +})); diff --git a/test/model/LibcalUtilisationSpaceSummary.spec.js b/test/model/LibcalUtilisationSpaceSummary.spec.js new file mode 100644 index 00000000..2cada0ca --- /dev/null +++ b/test/model/LibcalUtilisationSpaceSummary.spec.js @@ -0,0 +1,77 @@ +/** + * UCL API + * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` + * + * The version of the OpenAPI document: 1.4.2 + * Contact: isd.apiteam@ucl.ac.uk + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + * + */ + +(function(root, factory) { + if (typeof define === 'function' && define.amd) { + // AMD. + define(['expect.js', process.cwd()+'/src/index'], factory); + } else if (typeof module === 'object' && module.exports) { + // CommonJS-like environments that support module.exports, like Node. + factory(require('expect.js'), require(process.cwd()+'/src/index')); + } else { + // Browser globals (root is window) + factory(root.expect, root.uclapi); + } +}(this, function(expect, uclapi) { + 'use strict'; + + var instance; + + beforeEach(function() { + instance = new uclapi.LibcalUtilisationSpaceSummary(); + }); + + var getProperty = function(object, getter, property) { + // Use getter method if present; otherwise, get the property directly. + if (typeof object[getter] === 'function') + return object[getter](); + else + return object[property]; + } + + var setProperty = function(object, setter, property, value) { + // Use setter method if present; otherwise, set the property directly. + if (typeof object[setter] === 'function') + object[setter](value); + else + object[property] = value; + } + + describe('LibcalUtilisationSpaceSummary', function() { + it('should create an instance of LibcalUtilisationSpaceSummary', function() { + // uncomment below and update the code to test LibcalUtilisationSpaceSummary + //var instane = new uclapi.LibcalUtilisationSpaceSummary(); + //expect(instance).to.be.a(uclapi.LibcalUtilisationSpaceSummary); + }); + + it('should have the property active (base name: "active")', function() { + // uncomment below and update the code to test the property active + //var instance = new uclapi.LibcalUtilisationSpaceSummary(); + //expect(instance).to.be(); + }); + + it('should have the property bookableCount (base name: "bookable_count")', function() { + // uncomment below and update the code to test the property bookableCount + //var instance = new uclapi.LibcalUtilisationSpaceSummary(); + //expect(instance).to.be(); + }); + + it('should have the property total (base name: "total")', function() { + // uncomment below and update the code to test the property total + //var instance = new uclapi.LibcalUtilisationSpaceSummary(); + //expect(instance).to.be(); + }); + + }); + +})); diff --git a/test/model/LibcalZone.spec.js b/test/model/LibcalZone.spec.js new file mode 100644 index 00000000..09190733 --- /dev/null +++ b/test/model/LibcalZone.spec.js @@ -0,0 +1,71 @@ +/** + * UCL API + * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` + * + * The version of the OpenAPI document: 1.4.2 + * Contact: isd.apiteam@ucl.ac.uk + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + * + */ + +(function(root, factory) { + if (typeof define === 'function' && define.amd) { + // AMD. + define(['expect.js', process.cwd()+'/src/index'], factory); + } else if (typeof module === 'object' && module.exports) { + // CommonJS-like environments that support module.exports, like Node. + factory(require('expect.js'), require(process.cwd()+'/src/index')); + } else { + // Browser globals (root is window) + factory(root.expect, root.uclapi); + } +}(this, function(expect, uclapi) { + 'use strict'; + + var instance; + + beforeEach(function() { + instance = new uclapi.LibcalZone(); + }); + + var getProperty = function(object, getter, property) { + // Use getter method if present; otherwise, get the property directly. + if (typeof object[getter] === 'function') + return object[getter](); + else + return object[property]; + } + + var setProperty = function(object, setter, property, value) { + // Use setter method if present; otherwise, set the property directly. + if (typeof object[setter] === 'function') + object[setter](value); + else + object[property] = value; + } + + describe('LibcalZone', function() { + it('should create an instance of LibcalZone', function() { + // uncomment below and update the code to test LibcalZone + //var instane = new uclapi.LibcalZone(); + //expect(instance).to.be.a(uclapi.LibcalZone); + }); + + it('should have the property id (base name: "id")', function() { + // uncomment below and update the code to test the property id + //var instance = new uclapi.LibcalZone(); + //expect(instance).to.be(); + }); + + it('should have the property name (base name: "name")', function() { + // uncomment below and update the code to test the property name + //var instance = new uclapi.LibcalZone(); + //expect(instance).to.be(); + }); + + }); + +})); diff --git a/test/model/Location.spec.js b/test/model/Location.spec.js index d0385e3e..b0fcfe67 100644 --- a/test/model/Location.spec.js +++ b/test/model/Location.spec.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/LocationCoordinates.spec.js b/test/model/LocationCoordinates.spec.js index ee9fa25e..38ba0224 100644 --- a/test/model/LocationCoordinates.spec.js +++ b/test/model/LocationCoordinates.spec.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/Map.spec.js b/test/model/Map.spec.js index 75004e95..add75cfb 100644 --- a/test/model/Map.spec.js +++ b/test/model/Map.spec.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/MapWithSensors.spec.js b/test/model/MapWithSensors.spec.js index 39d6fd52..f06df465 100644 --- a/test/model/MapWithSensors.spec.js +++ b/test/model/MapWithSensors.spec.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/Module.spec.js b/test/model/Module.spec.js index 1ba47e92..cf5944b6 100644 --- a/test/model/Module.spec.js +++ b/test/model/Module.spec.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/ModuleDataCoursesModules.spec.js b/test/model/ModuleDataCoursesModules.spec.js index a3f8c9c6..2c717066 100644 --- a/test/model/ModuleDataCoursesModules.spec.js +++ b/test/model/ModuleDataCoursesModules.spec.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/Period.spec.js b/test/model/Period.spec.js index 17569c8b..97b23397 100644 --- a/test/model/Period.spec.js +++ b/test/model/Period.spec.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/Person.spec.js b/test/model/Person.spec.js index 7c185f02..c3c08022 100644 --- a/test/model/Person.spec.js +++ b/test/model/Person.spec.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/Room.spec.js b/test/model/Room.spec.js index f6405835..720724bc 100644 --- a/test/model/Room.spec.js +++ b/test/model/Room.spec.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/RoomLocation.spec.js b/test/model/RoomLocation.spec.js index 93763a60..081f4f76 100644 --- a/test/model/RoomLocation.spec.js +++ b/test/model/RoomLocation.spec.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/SeatImage.spec.js b/test/model/SeatImage.spec.js index d7af35e5..6aa1c9df 100644 --- a/test/model/SeatImage.spec.js +++ b/test/model/SeatImage.spec.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/SeatImageCircle.spec.js b/test/model/SeatImageCircle.spec.js index fd192d82..891a0db0 100644 --- a/test/model/SeatImageCircle.spec.js +++ b/test/model/SeatImageCircle.spec.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/Sensor.spec.js b/test/model/Sensor.spec.js index 365de72f..e64cdf92 100644 --- a/test/model/Sensor.spec.js +++ b/test/model/Sensor.spec.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/SensorAverageSurvey.spec.js b/test/model/SensorAverageSurvey.spec.js index 8eae6257..7574047f 100644 --- a/test/model/SensorAverageSurvey.spec.js +++ b/test/model/SensorAverageSurvey.spec.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/SummerSchool.spec.js b/test/model/SummerSchool.spec.js index 76fef4d5..2b50a3ba 100644 --- a/test/model/SummerSchool.spec.js +++ b/test/model/SummerSchool.spec.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/SummerSchoolSessions.spec.js b/test/model/SummerSchoolSessions.spec.js index 9d15999b..cc49ff1d 100644 --- a/test/model/SummerSchoolSessions.spec.js +++ b/test/model/SummerSchoolSessions.spec.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/Survey.spec.js b/test/model/Survey.spec.js index bf94a0d3..365b2c73 100644 --- a/test/model/Survey.spec.js +++ b/test/model/Survey.spec.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/SurveyLocation.spec.js b/test/model/SurveyLocation.spec.js index fe0ee7bb..7dec7d79 100644 --- a/test/model/SurveyLocation.spec.js +++ b/test/model/SurveyLocation.spec.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/SurveyLocationCoordinates.spec.js b/test/model/SurveyLocationCoordinates.spec.js index 724a4627..021722ca 100644 --- a/test/model/SurveyLocationCoordinates.spec.js +++ b/test/model/SurveyLocationCoordinates.spec.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/SurveyWithMaps.spec.js b/test/model/SurveyWithMaps.spec.js index b7621f04..0f7b99f1 100644 --- a/test/model/SurveyWithMaps.spec.js +++ b/test/model/SurveyWithMaps.spec.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/Svg.spec.js b/test/model/Svg.spec.js index 93dcfbb3..0428759c 100644 --- a/test/model/Svg.spec.js +++ b/test/model/Svg.spec.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/SvgG.spec.js b/test/model/SvgG.spec.js index 178825de..fb5eabaa 100644 --- a/test/model/SvgG.spec.js +++ b/test/model/SvgG.spec.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/SvgGImage.spec.js b/test/model/SvgGImage.spec.js index 44299292..8e809d50 100644 --- a/test/model/SvgGImage.spec.js +++ b/test/model/SvgGImage.spec.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/TeachingPeriods.spec.js b/test/model/TeachingPeriods.spec.js index d767ef6f..ecaeed6b 100644 --- a/test/model/TeachingPeriods.spec.js +++ b/test/model/TeachingPeriods.spec.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/Timetable.spec.js b/test/model/Timetable.spec.js index 17ccfa97..8ee5c1f1 100644 --- a/test/model/Timetable.spec.js +++ b/test/model/Timetable.spec.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/UserData.spec.js b/test/model/UserData.spec.js index 495e94ef..08e8d91f 100644 --- a/test/model/UserData.spec.js +++ b/test/model/UserData.spec.js @@ -2,7 +2,7 @@ * UCL API * An API generated by a team of student developers to interact with student and university data at UCL. The API is made up of several services, each of which will be separately explained. Every service will be documented here with important information, tips and examples. ## Get Your API Key Before you can use the API you should head to the API Dashboard and sign up using your UCL user account. Once logged into the dashboard simply name your app and you’ll be given a key that you can use to access all the services. Simple! ## API Rate Limits Rate limiting of the API is primarily on a per-user basis. The limit is calculated against the user, across all their access tokens. The limit is 10,000 requests per day and resets every day at midnight, London time. When a request is throttled, the response returned by the server has HTTP Status Code “429 Too Many Requests”. It includes a Retry-After header with the number of seconds the client is throttled for. If you would like your rate limit to be increased, contact us at isd.apiteam@ucl.ac.uk ## API Data Freshness Much of the data available from the API is served from cache. Bookings and Timetable data are updated every twenty minutes from UCL, and we update the [Library Study Spaces (Workspaces) API](https://uclapi.com/docs/#workspaces) every two minutes. The `Last-Modified` header will provide the time that the most recent caching operation completed in [RFC 2616](https://stackoverflow.com/a/21121453) format. Endpoints that do not rely on cached data will return the current timestamp in this field instead. This allows your application to judge whether the data is stale, or might need refreshing. For example, if a booking is added to the database and the data you are using is more than twenty minutes old, it may be that the booking is not visible to you yet. Consider creating a fresh request in this case. If you notice that the `Last-Modified` timestamp you see is unreasonably old, please [get in contact with us](mailto:isd.apiteam@ucl.ac.uk) ASAP to report this as it may indicate very stale data and an issue at our end. ## OAuth OAuth is a protocol that lets external apps request secure access to private UCL account data without getting your password. This can be done with a \"Sign In With UCL\" button on your website or app which saves UCL users the trouble of registering a new account with you. It also allows your app or website to retrieve a user's personal timetable. Check out a JS web app demo [here](https://uclapi-oauth-demo.glitch.me/). The source code for the demo is available [here](https://glitch.com/edit/#!/uclapi-oauth-demo). For an example of a mobile app implementation, check out [UCL Assistant](https://github.com/uclapi/ucl-assistant-app) (written in React Native) and the accompanying [UCL Assistant API backend](https://github.com/uclapi/ucl-assistant-api/tree/master/src/oauth) (written in Node.JS). ### Sign In With UCL Button If you want to add a \"Sign In With UCL\" button to your site, which looks like this: you can copy the following the code below and replace CLIENT_ID and STATE by the `client_id` of your app and a random `state`: ``` ``` ### Scopes OAuth scopes specify what access your app needs to a UCL user’s account. As an app developer, you set the desired scopes in the API Dashboard. When a user is responding to your authorisation request, the requested scopes will be displayed to the user. ### OAuth Workflow If your application uses OAuth, you must set a callback URL in the dashboard. Then the app should follow this procedure: 1. Redirect the user to `https://uclapi.com/oauth/authorise` with `state` and the application’s `client_id` as query parameters. 2. The user logs in with their UCL credentials on the UCL Single Sign-on website (if not logged in already). 3. The user reviews the OAuth scopes requested and either authorises or denies the application's request. If the application is authorised, the callback URL receives `client_id`, `state` (specified in 1.), `result`, and `code`. If the application is denied, the callback URL receives `result` and `state`, and no private data will be provided to the application. 4. To obtain a OAuth user token (necessary for retrieving personal data and certain API endpoints), we require `code` (from 3.), `client_id`, and `client_secret`. These should then be sent to `https://uclapi.com/oauth/token`, which will return a response containing `state`, `ok`, `client_id`, `token` (OAuth user token), and `scope` (OAuth scopes the app can access on the user’s behalf). **Note**: OAuth tokens and general API tokes are different. Whilst general API tokens can be used for all non-personal, generic data (such as room bookings), OAuth tokens must be used with an app's client_secret in order to retrieve personal data for a user. To make things easier, you can use personal OAuth tokens in place of general tokens once a user has logged into your app to retrieve generic data too. ### Tokens Tokens uniquely identify an app that is requesting data from the API. Tokens are a long string variable of numbers and letters. e.g. `uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb`. There are two different kinds of tokens you can work with: 1. Generic Tokens: These are tokens that are used to request non-personal data. These tokens are used between applications and the API to request any sort of data that the app may need that is not tied to a specific student. For example, UCL API’s Room booking service uses tokens to return information about rooms - when they are booked and which UCL rooms are free. 2. OAuth Tokens: This type of token is used when an app requires personal data from users. One of the most common uses of this type of token is when you sign in via UCL on an app. The app will then use a token to request a user’s personal data such as: - Department - Email - Full name - Given name - UPI - If they are a student or not - Student number (*note:* to get this, you need to tick the relevant scope in the dashboard before a user logs in; more on scopes above). Note that you can also use OAuth Tokens to access all the same data that generic app tokens can access. Each token is uniquely generated for each user logging into each app. Please note, access to any of this data needs to be approved by the user first. To use this type of token for your app, you need to redirect the user to the \"Authorise\" endpoint at: `https://uclapi.com/oauth/authorise` which can be done directly or by including a “Sign in With UCL Button” in your app, such as the one provided below, which links users to the authorisation endpoint with your app’s Client ID (accessible via the dashboard) and a random state number included in the GET parameters. The users then sign in with their UCL credentials and, if they authorise your app to use their personal data, a token will be generated which your app can use to get user’s personal data in JSON format from the oauth/user/data. Your application will receive the token at the callback URL you provided in the [Dashboard](https://uclapi.com/dashboard). ## Code Samples After authorisation, calling most of the API endpoints will be fairly similar to each other. Authorisation code samples are provided in their respective descriptions. In addition, please find short code examples of how you might call the `/roombookings/equipment` endpoint in your own code (you will find that only the request parameters will change between most different endpoints): Python: ```python import requests params = { \"token\": \"uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb\", \"roomid\": \"433\" \"siteid\": \"086\" } r = requests.get(\"https://uclapi.com/roombookings/equipment\", params=params) print(r.json()) ``` Shell: ```shell curl -G https://uclapi.com/roombookings/equipment -d token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb -d roomid=433 -d siteid=086 ``` JavaScript: ```js fetch(\"https://uclapi.com/roombookings/equipment?token=uclapi-5d58c3c4e6bf9c-c2910ad3b6e054-7ef60f44f1c14f-a05147bfd17fdb&roomid=433&siteid=086\") .then(response => response.json()) .then(json => console.log(json)); ``` * - * The version of the OpenAPI document: 1.0.3 + * The version of the OpenAPI document: 1.4.2 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/uclapi.openapi.json b/uclapi.openapi.json index ccb38f76..033255d9 100644 --- a/uclapi.openapi.json +++ b/uclapi.openapi.json @@ -8,7 +8,7 @@ "email": "isd.apiteam@ucl.ac.uk", "url": "https://uclapi.com" }, - "version": "1.0.3", + "version": "1.4.2", "termsOfService": "https://github.com/uclapi/uclapi/blob/master/backend/uclapi/uclapi/UCLAPIAcceptableUsePolicy.txt", "license": { "url": "https://github.com/uclapi/uclapi/blob/master/LICENSE", @@ -40,6 +40,10 @@ "name": "Workspaces", "description": "Fetch workspace availablility and maps throughout UCL" }, + { + "name": "LibCal", + "description": "Manage and make seat reservations on the library booking system" + }, { "name": "Analytics", "description": "View analytics and stats about your app or API services" @@ -280,1319 +284,3263 @@ "schema": { "type": "boolean" } + }, + "libcal_details": { + "name": "details", + "in": "query", + "description": "Flag to indicate you want additional details such as terms and conditions.", + "required": false, + "example": 1, + "schema": { + "type": "integer" + } + }, + "libcal_location_id": { + "name": "ids", + "in": "query", + "description": "A single LibCal location ID", + "required": true, + "example": "702", + "schema": { + "type": "string" + } + }, + "libcal_location_ids": { + "name": "ids", + "in": "query", + "description": "Comma delimited list of LibCal location IDs", + "required": true, + "example": "702,703", + "schema": { + "type": "string" + } + }, + "libcal_category_id": { + "name": "category_id", + "in": "query", + "description": "If specified, will only return data for that category", + "required": false, + "example": "3334", + "schema": { + "type": "string" + } + }, + "libcal_category_ids": { + "name": "ids", + "in": "query", + "description": "Comma delimited list of LibCal category IDs", + "required": true, + "example": "3334,3335", + "schema": { + "type": "string" + } + }, + "libcal_availability": { + "name": "availability", + "in": "query", + "description": "Either a single date or a comma delimited list of 2 dates (a start and end date). The keyword 'next' (alone) can also be used to return availability for the next date that this item is available. Setting this parameter also sets the details value to 1. Dates should be in YYYY-MM-DD format.", + "example": "2021-01-05", + "schema": { + "type": "string" + }, + "required": false + }, + "libcal_form_ids": { + "name": "ids", + "in": "query", + "description": "Comma delimited list of LibCal form IDs", + "required": true, + "example": "38,62", + "schema": { + "type": "string" + } + }, + "libcal_field_ids": { + "name": "ids", + "in": "query", + "description": "Comma delimited list of LibCal field/question IDs", + "required": true, + "example": "43,8", + "schema": { + "type": "string" + } + }, + "libcal_space_id": { + "name": "space_id", + "in": "query", + "description": "If specified, only return data for this space", + "required": false, + "example": "1791", + "schema": { + "type": "string" + } + }, + "libcal_space_ids": { + "name": "ids", + "in": "query", + "description": "Comma delimited list of LibCal space IDs", + "required": true, + "example": "469,470", + "schema": { + "type": "string" + } + }, + "libcal_zone_id": { + "name": "zone_id", + "in": "query", + "description": "If specified, will only return data for that zone", + "required": false, + "example": "87", + "schema": { + "type": "string" + } + }, + "libcal_seat_id": { + "name": "ids", + "in": "query", + "description": "A single LibCal seat ID", + "required": true, + "example": "54435", + "schema": { + "type": "string" + } + }, + "libcal_accessible_only": { + "name": "accessible_only", + "in": "query", + "description": "Return only acessible seats (i.e. seats with height-adjustable furniture).", + "required": false, + "example": false, + "schema": { + "type": "boolean" + } + }, + "libcal_page_index": { + "name": "page_index", + "in": "query", + "description": "For pagination purposes, this specifies the page to be retrieved. Starts at 0 for the first page.", + "required": false, + "example": 0, + "schema": { + "type": "integer" + } + }, + "libcal_page_size": { + "name": "page_size", + "in": "query", + "description": "For pagination purposes, this specifies the number of results per page. Must be >= 1 and <= 100. The default is 20.", + "required": false, + "example": 10, + "schema": { + "type": "integer" + } + }, + "libcal_booking_ids": { + "name": "id", + "in": "query", + "description": "A comma delimited list of LibCal booking IDs to cancel", + "required": true, + "example": "cs_loYG4wTz,ab_P1bn30Mn", + "schema": { + "type": "string" + } } }, "schemas": { - "user_data": { + "libcal_reserve_request_booking": { + "description": "Specify seat_id if booking a seat, otherwise omit it", "properties": { - "ok": { - "type": "boolean", - "example": "true", - "description": "Returns if the query was successful." + "id": { + "$ref": "#/components/schemas/libcal_space_id" }, - "email": { - "type": "string", - "example": "xxxxxxx@ucl.ac.uk", - "description": "Email address for the given user." + "to": { + "$ref": "#/components/schemas/libcal_booking_end" }, - "full_name": { - "type": "string", - "example": "John Doe", - "description": "Full name of the user. Can be an empty string." + "seat_id": { + "$ref": "#/components/schemas/libcal_seat_id" + } + }, + "required": [ + "id", + "to" + ] + }, + "libcal_reserve_request": { + "properties": { + "start": { + "$ref": "#/components/schemas/libcal_booking_start" }, - "department": { - "type": "string", - "example": "Dept of Computer Science", - "description": "Department the user belongs to. Can be an empty string." + "test": { + "type": "integer", + "description": "Whether or not this is a test booking. If set, the system will process the booking but will not actually make it. This is useful during development.", + "example": 1 }, - "cn": { + "nickname": { "type": "string", - "example": "xxxxxxx", - "description": "UCL username of the given user." + "description": "If the space to be booked has a nickname, then the nickname must be supplied here.", + "example": "Tutorial Group Y" }, - "given_name": { - "type": "string", - "example": "John", - "description": "Given first name of the user. Can be an empty string." + "bookings": { + "type": "array", + "items": { + "$ref": "#/components/schemas/libcal_reserve_request_booking" + } + } + }, + "required": [ + "start", + "test" + ] + }, + "libcal_personal_seat_booking": { + "allOf": [ + { + "$ref": "#/components/schemas/libcal_seat_booking" + } + ], + "properties": { + "book_id": { + "$ref": "#/components/schemas/libcal_booking_id" }, - "upi": { + "first_name": { "type": "string", - "example": "jdoe12", - "description": "Unique Person Identifier." + "description": "First name of the user who booked this", + "example": "Jeremy" }, - "scope_number": { - "type": "integer", - "format": "int64", - "example": 0, - "description": "Scopes the application has access to on behalf of the user." + "last_name": { + "type": "string", + "description": "Last name of the user who booked this", + "example": "Bentham" }, - "is_student": { - "type": "boolean", - "example": true, - "description": "Whether the user is a student in this academic year." + "email": { + "type": "string", + "description": "Email address of the user who booked this", + "example": "jeremy.bentham.00@ucl.ac.uk" }, - "ucl_groups": { + "check_in_code": { "type": "string", - "example": "ucl-all;ucl-ug", - "description": "A semi-colon delimited string of all UCL intranet groups that the user belongs to." + "description": "Email address of the user who booked this", + "example": "2A9" } } }, - "event": { + "libcal_seat_booking": { "properties": { - "location": { - "$ref": "#/components/schemas/location" + "eid": { + "$ref": "#/components/schemas/libcal_space_id" }, - "module": { - "$ref": "#/components/schemas/module" + "cid": { + "$ref": "#/components/schemas/libcal_category_id" }, - "start_time": { - "type": "string", - "example": "2016-09-02T09:00:00+00:00", - "description": "Start time of the event." + "lid": { + "$ref": "#/components/schemas/libcal_location_id" }, - "end_time": { - "type": "string", - "example": "2016-09-02T10:00:00+00:00", - "description": "End time of the event." + "from_date": { + "$ref": "#/components/schemas/libcal_booking_start" }, - "duration": { - "type": "integer", - "format": "int64", - "example": 60, - "description": "Duration of the event in minutes." + "to_date": { + "$ref": "#/components/schemas/libcal_booking_end" }, - "session_type": { - "type": "string", - "example": "L", - "description": "ID of the type of session, e.g. L = Lecture, PBL = Problem Based Learning. These come from UCL's internal database, and are provided in case a new session type that we are not aware of is in the timetable. See session_type_str below." + "created": { + "$ref": "#/components/schemas/libcal_booking_created" }, - "session_type_str": { + "status": { "type": "string", - "example": "Lecture", - "description": "Type of event such as Lecture, Problem Based Learning, Practical, etc. If the session_type has not been recognised by us then this will have the value Unknown." + "description": "Status of this LibCal booking", + "example": "Confirmed" }, - "session_group": { - "type": "string", - "example": "", - "description": "Used for lab groups, or other types of small group activity that does not involve the whole cohort. When the whole cohort is invited (e.g. lectures) this value is a blank string. In the personal timetable endpoint only the labs / group sessions assigned to the user with the OAuth token provided will be returned. For example, if the user is in LAB A then Labs B onwards will not be returned." + "location_name": { + "$ref": "#/components/schemas/libcal_location_name" }, - "session_title": { - "type": "string", - "example": "Computational Complexity A", - "description": "The title of the event." + "category_name": { + "$ref": "#/components/schemas/libcal_category_name" }, - "contact": { - "type": "string", - "example": "Prof Robin Hirsch", - "description": "The name associated with the individual room booking. This is the most likely candidate for the person taking the session or lecture. This name is also the most human-readable. Apps should display this value as the lecturer for any given booking, and only use the lecturer information given in the module{lecturer{}} dictionary to reference the course lead or owner." + "item_name": { + "$ref": "#/components/schemas/libcal_space_name" + }, + "seat_id": { + "$ref": "#/components/schemas/libcal_seat_id" + }, + "seat_name": { + "$ref": "#/components/schemas/libcal_seat_name" + }, + "cancelled": { + "$ref": "#/components/schemas/libcal_cancelled" } } }, - "module": { + "libcal_location_id": { + "type": "integer", + "description": "LibCal Location ID", + "example": 700 + }, + "libcal_seat_id": { + "type": "integer", + "description": "LibCal seat ID", + "example": 54435 + }, + "libcal_seat_name": { + "type": "string", + "description": "Name of the LibCal seat", + "example": "367 - Donaldson Reading Room (Law)" + }, + "libcal_cancelled": { + "type": "string", + "description": "Timestamp (in ISO 8601 format) at which this LibCal booking was cancelled, if applicable", + "example": "2021-01-14T09:00:00+00:00" + }, + "libcal_seat": { "properties": { - "lecturer": { - "$ref": "#/components/schemas/lecturer" - }, - "module_id": { - "type": "string", - "example": "COMP3004", - "description": "Module ID." + "id": { + "$ref": "#/components/schemas/libcal_seat_id" }, "name": { - "type": "string", - "example": "Computational Complexity", - "description": "Module name." + "$ref": "#/components/schemas/libcal_seat_name" }, - "department_id": { + "description": { "type": "string", - "example": "COMPS_ENG", - "description": "Department code that this module comes under." + "description": "Description provided for the LibCal seat. May contain HTML", + "example": "

Donaldson Reading Room (Law)

" }, - "department_name": { + "is_accessible": { + "type": "boolean", + "description": "Whether the seat is height-adjustable and hence accessible by the differently-abled", + "example": true + }, + "is_powered": { + "type": "boolean", + "description": "Whether a power socket is available at the seat", + "example": true + }, + "image": { "type": "string", - "example": "Computer Science", - "description": "Human readable department name that owns the module." + "description": "A URL pointing to an image of the seat. If none is available, an empty string will be returned", + "example": "https://example.org/seat.png" + }, + "status": { + "type": "boolean", + "description": "The current status of the seat", + "example": true } } }, - "timetable": { + "libcal_zone_id": { + "type": "integer", + "description": "LibCal Zone ID", + "example": 2263 + }, + "libcal_zone_name": { + "type": "string", + "description": "Name of the LibCal zone", + "example": "Fourth Floor North" + }, + "libcal_zone": { "properties": { - "date": { - "type": "array", - "items": { - "$ref": "#/components/schemas/event" - } + "id": { + "$ref": "#/components/schemas/libcal_zone_id" + }, + "name": { + "$ref": "#/components/schemas/libcal_zone_name" } } }, - "module_data_courses_modules": { + "libcal_utilisation_seat_summary": { "properties": { - "module_id": { - "type": "string", - "example": "COMP3004", - "description": "Module ID." + "active": { + "type": "integer", + "description": "Number of active LibCal bookings of seats", + "example": 2 }, - "name": { - "type": "string", - "example": "Computational Complexity", - "description": "Module name." + "bookable_count": { + "type": "integer", + "description": "Number of LibCal seats available to be booked", + "example": 98 }, - "instances": { - "type": "array", - "items": { - "$ref": "#/components/schemas/instance" - } + "total": { + "type": "integer", + "description": "Total number of LibCal seats in the location", + "example": 100 } } }, - "instance": { + "libcal_utilisation_space_summary": { "properties": { - "full_module_id": { - "type": "string", - "example": "MATH--82-A7P-T2", - "description": "The module code concatenated with the instance data. This instance data is defined by the UCL Academic Model Project, and it is expanded out within this section." - }, - "class_size": { - "type": "number", - "example": 12, - "description": "The maximum number of students in the module permitted in that instance. In this example, twelve undergraduates are permitted to take this module in their third year, but ninety postgraduates may take the module." - }, - "delivery": { - "$ref": "#/components/schemas/delivery" - }, - "periods": { - "$ref": "#/components/schemas/period" - }, - "instance_code": { - "type": "string", - "example": "A7P-T2", - "description": "A code that, when combined with a module code, forms the 'full_module_id' field above. This data is used to calculate the delivery and periods information that is also provided via JSON. Concatenating the module_id, a hyphen and the instance_code forms the full_module_id field." - } - } - }, - "delivery": { - "properties": { - "fheq_level": { + "active": { "type": "integer", - "example": 7, - "description": "The level the course is taught at, and whether it is an undergraduate (true) or postgraduate (false) course." + "description": "Number of active LibCal bookings of spaces", + "example": 2 }, - "is_undergraduate": { - "type": "boolean", - "example": true, - "description": "Whether the course instance is for undergraduate (true) students or postgraduate (false) students." + "bookable_count": { + "type": "integer", + "description": "Number of LibCal spaces available to be booked", + "example": 28 }, - "student_type": { - "type": "string", - "example": "Campus-based, numeric mark scheme", - "description": "The type of student and assessment pattern available for that course. There are five options: 'Campus-based, numeric mark scheme', 'Campus-based, non-numeric mark scheme', 'Distance learner, numeric mark scheme', 'Distance learner, non-numeric mark scheme' and 'MBBS Resit'." + "total": { + "type": "integer", + "description": "Total number of LibCal spaces in the location", + "example": 30 } } }, - "period": { + "libcal_booking_start": { + "type": "string", + "example": "2021-01-14T09:00:00+00:00", + "description": "Timestamp (in ISO 8601 format) at which this LibCal booking starts" + }, + "libcal_booking_end": { + "type": "string", + "example": "2021-01-14T09:00:00+00:00", + "description": "Timestamp (in ISO 8601 format) at which this LibCal booking ends" + }, + "libcal_booking_created": { + "type": "string", + "example": "2021-01-12T09:00:00+00:00", + "description": "Timestamp (in ISO 8601 format) denoting when this LibCal booking was created" + }, + "libcal_booking_id": { + "type": "string", + "example": "_L4oMxm", + "description": "ID assigned to this LibCal booking" + }, + "libcal_booking": { "properties": { - "teaching_periods": { - "$ref": "#/components/schemas/teaching_periods" + "nickname": { + "type": "string", + "description": "Nickname assigned to this LibCal booking", + "example": "LAWS0339: Internet Law and Policy Seminar Group G" }, - "year_long": { - "type": "boolean", - "example": false, - "description": "Whether the course is timetabled to last for an entire academic year." + "start": { + "$ref": "#/components/schemas/libcal_booking_start" }, - "lsr": { - "type": "boolean", - "example": false, - "description": "Whether the module is timetabled during the Late Summer Resit period. This is used internally by Examinations to timetable Late Summer Assessments (LSAs)." + "end": { + "$ref": "#/components/schemas/libcal_booking_end" }, - "summer_school": { - "$ref": "#/components/schemas/summer_school" + "created": { + "$ref": "#/components/schemas/libcal_booking_created" + }, + "booking_id": { + "$ref": "#/components/schemas/libcal_booking_id" } } }, - "teaching_periods": { + "libcal_space_id": { + "type": "integer", + "example": 469, + "description": "ID of this LibCal space" + }, + "libcal_space_name": { + "type": "string", + "example": "Study Room 1", + "description": "Name of this LibCal space" + }, + "libcal_space_base": { "properties": { - "term_1": { - "type": "boolean", - "example": false, - "description": "Whether the course is taught during Term 1." + "id": { + "$ref": "#/components/schemas/libcal_space_id" }, - "term_2": { - "type": "boolean", - "example": true, - "description": "Whether the course is taught during Term 2." + "name": { + "$ref": "#/components/schemas/libcal_space_name" }, - "term_3": { - "type": "boolean", - "example": false, - "description": "Whether the course is taught during Term 3." + "description": { + "type": "string", + "example": "A place for quiet study", + "description": "Description of this LibCal space" }, - "term_1_next_year": { - "type": "boolean", - "example": false, - "description": "Whether the course is taught during Term 1 of the following academic year. This is used by admissions to calculate the end dates for non-standard programmes, and therefore is rare." + "image": { + "type": "string", + "example": "https://example.org/image.jpg", + "description": "URL pointing to an image depicting this LibCal space" }, - "summer": { - "type": "boolean", - "example": false, - "description": "Whether the course timetabled during the summer holidays. This can happen in some Postgraduate and Medicine teaching arrangements, but is rare. Note that this is NOT the same as the UCL Summer School." + "capacity": { + "type": "integer", + "example": 4, + "description": "Maximum number of persons this LibCal space can accommodate" + }, + "formid": { + "type": "integer", + "example": 14, + "description": "ID of the form associated with this LibCal space" } } }, - "summer_school": { - "properties": { - "is_summer_school": { - "type": "boolean", - "example": false, - "description": "Whether the module is taught as part of the UCL Summer School (true) or standard academic teaching (false)." - }, - "sessions": { - "type": "object", - "properties": { - "session_1": { - "type": "boolean", - "example": false, - "description": "Whether the module is taught in the first summer school session of this academic year's summer. This will be false for all standard academic modules." - }, - "session_2": { - "type": "boolean", - "example": false, - "description": "Whether the module is taught in the second summer school session of this academic year's summer. This will be false for all standard academic modules." - } + "libcal_space_availability": { + "type": "array", + "items": { + "properties": { + "from": { + "type": "string", + "example": "2021-01-14T09:00:00+00:00", + "description": "Timestamp (in ISO 8601 format) from which this LibCal space is available to be booked" + }, + "to": { + "type": "string", + "example": "2021-01-14T10:00:00+00:00", + "description": "Timestamp (in ISO 8601 format) to which this LibCal space is available to be booked" } } } }, - "lecturer": { + "libcal_form_field": { "properties": { - "name": { + "label": { "type": "string", - "example": "HUNTER, Anthony (Prof)", - "description": "Name of lecturer" + "example": "First Name", + "description": "Label for the field in the LibCal booking form" }, - "department_name": { + "type": { "type": "string", - "example": "Computer Science", - "description": "Human readable department name that owns the module." + "example": "string", + "description": "Field type for the field in the LibCal booking form. Examples of field types include 'string' and 'dropdown'." }, - "department_id": { - "type": "string", - "example": "COMPS_ENG", - "description": "Department code that this module comes under." + "required": { + "type": "boolean", + "example": false, + "description": "Whether the field in the LibCal booking form is required (true) or optional (false)" }, - "email": { - "type": "string", - "example": "ucachun@ucl.ac.uk", - "description": "Email address for lecturer" + "options": { + "type": "array", + "items": { + "type": "string", + "example": "Medicine" + }, + "description": "Array of options that will be provided if the field type is dropdown" } } }, - "location": { + "libcal_form_id": { + "type": "integer", + "example": 0, + "description": "LibCal booking form ID" + }, + "libcal_form": { "properties": { + "id": { + "$ref": "#/components/schemas/libcal_form_id" + }, "name": { "type": "string", - "example": "Roberts Building 421", - "description": "Room name of the timetable event." + "example": "COVID Health Check", + "description": "Name of the LibCal booking form" }, - "address": { + "fields": { "type": "array", - "minItems": 4, - "maxItems": 4, "items": { - "type": "string" - }, - "example": [ - "Torrington Place", - "London", - "WC1E 7JE" - ], - "description": "Address represented as an array." - }, - "site_name": { - "type": "string", - "example": "Roberts Building", - "description": "Name of the site / building where the event is happening." + "$ref": "#/components/schemas/libcal_form_field" + } + } + } + }, + "libcal_category_id": { + "type": "integer", + "example": 3334, + "description": "LibCal category ID denoting a category assigned to a particular space" + }, + "libcal_category_public": { + "type": "integer", + "example": 0, + "description": "1 if the category of spaces is publicly-bookable, 0 if it is not" + }, + "libcal_category_name": { + "type": "string", + "example": "Study Space", + "description": "Name of the category" + }, + "libcal_category": { + "properties": { + "cid": { + "$ref": "#/components/schemas/libcal_category_id" }, - "type": { - "type": "string", - "example": "CB", - "description": "Type of the room eg., Centrally Bookable (CB) or Departmentally Bookable (DB)." + "formid": { + "$ref": "#/components/schemas/libcal_form_id" }, - "capacity": { - "type": "integer", - "example": 94, - "description": "Capacity of the room (e.g. how many seats are in a lecture theatre, or how many can be sat at tables in a flat space)." + "name": { + "$ref": "#/components/schemas/libcal_category_name" }, - "coordinates": { - "type": "object", - "properties": { - "lat": { - "type": "string", - "example": "51.524699", - "description": "Latitude of location" - }, - "lng": { - "type": "string", - "example": "-0.13366", - "description": "Longitude of location" - } - } + "public": { + "$ref": "#/components/schemas/libcal_category_public" } } }, - "department": { + "libcal_location_name": { + "type": "string", + "example": "Bartlett Library", + "description": "Name of the LibCal location in question" + }, + "libcal_location_base": { "properties": { - "department_id": { - "type": "string", - "example": "COMPS_ENG", - "description": "Department code." + "lid": { + "type": "integer", + "example": 702, + "description": "ID for the LibCal location in question" }, "name": { - "type": "string", - "example": "Computer Science", - "description": "Human readable department name." + "$ref": "#/components/schemas/libcal_location_name" } } }, - "course": { + "libcal_location": { + "allOf": [ + { + "$ref": "#/components/schemas/libcal_location_base" + } + ], "properties": { - "course_name": { - "type": "string", - "example": "MRes Computational Statistics and Machine Learning", - "description": "The human readable name for the module." - }, - "course_id": { - "type": "string", - "example": "TMRCOMSSML01", - "description": "The module code." - }, - "years": { + "public": { "type": "integer", "example": 1, - "description": "Length of the course given in years." + "description": "1 if the location is publicly-bookable, 0 if it is not" + }, + "terms": { + "type": "string", + "example": "You must bring your UCL ID and a copy of the confirmation email to gain access to the space.", + "description": "Additional details about the location, such as terms & conditions. May include HTML." } } }, - "room": { + "user_data": { "properties": { - "roomname": { - "type": "string", - "example": "Wilkins Building (Main Building) Portico", - "description": "The name of the room. It often includes the name of the site (building) as well." + "ok": { + "type": "boolean", + "example": "true", + "description": "Returns if the query was successful." }, - "roomid": { + "email": { "type": "string", - "example": "Z4", - "description": "The room ID (not to be confused with the roomname)." + "example": "xxxxxxx@ucl.ac.uk", + "description": "Email address for the given user." }, - "siteid": { + "full_name": { "type": "string", - "example": "005", - "description": "Every room is inside a site (building). All sites have IDs." + "example": "John Doe", + "description": "Full name of the user. Can be an empty string." }, - "sitename": { + "department": { "type": "string", - "example": "Main Building", - "description": "Every site (building) has a name. In some cases this is contained in the roomname as well." - }, - "capacity": { - "type": "integer", - "example": 50, - "description": "Every room has a set capacity of how many people can fit inside it. When supplied, all rooms with the given capacity or greater will be returned." + "example": "Dept of Computer Science", + "description": "Department the user belongs to. Can be an empty string." }, - "classification": { + "cn": { "type": "string", - "example": "SS", - "description": "The room type ID." + "example": "xxxxxxx", + "description": "UCL username of the given user." }, - "classification_name": { + "given_name": { "type": "string", - "example": "Social Space", - "description": "A human-readable version of the room type. AN = Anechoic Chamber, CI = Clinic Room, CF = Catering Facilities CFE = Cafe, CL = Cloakroom, CR = Classroom, ER = Equipment Room, IN = Installation, LA = Laboratory, LB = Library, LT = Lecture Theatre, MR = Meeting Room, OF = Office, PC1 = Public Cluster, PC2 = Public Cluster - Tutorial, PC3 = Public Cluster - Students, RC = Reverberation Chamber, SS = Social Space, STU = Studio, TH = Theatre. If the room type is unknown, this value will be set to 'Unknown Room Type'." + "example": "John", + "description": "Given first name of the user. Can be an empty string." }, - "automated": { + "upi": { "type": "string", - "example": "N", - "description": "Whether bookings in this room will be confirmed automatically. A stands for automated, and N for not automated. P represents that the confirmation will be automatic, but only under certain circumstances." + "example": "jdoe12", + "description": "Unique Person Identifier." }, - "location": { - "type": "object", - "properties": { - "address": { - "type": "array", - "minItems": 4, - "maxItems": 4, - "items": { - "type": "string" - }, - "example": [ - "Gower Street", - "London", - "WC1E 6BT" - ], - "description": "Address represented as an array." - }, - "coordinates": { - "type": "object", - "properties": { - "lat": { - "type": "string", - "example": "51.524699", - "description": "Latitude of location" - }, - "lng": { - "type": "string", - "example": "-0.13366", - "description": "Longitude of location" - } - } - } - } + "scope_number": { + "type": "integer", + "format": "int64", + "example": 0, + "description": "Scopes the application has access to on behalf of the user." + }, + "is_student": { + "type": "boolean", + "example": true, + "description": "Whether the user is a student in this academic year." + }, + "ucl_groups": { + "type": "string", + "example": "ucl-all;ucl-ug", + "description": "A semi-colon delimited string of all UCL intranet groups that the user belongs to." } } }, - "booking": { + "event": { "properties": { - "slotid": { - "type": "number", - "format": "int64", - "example": 998503, - "description": "Slot ID." + "location": { + "$ref": "#/components/schemas/location" + }, + "module": { + "$ref": "#/components/schemas/module" + }, + "start_time": { + "type": "string", + "example": "2016-09-02T09:00:00+00:00", + "description": "Start time of the event." }, "end_time": { "type": "string", - "example": "2016-09-02T18:00:00+00:00", + "example": "2016-09-02T10:00:00+00:00", "description": "End time of the event." }, - "description": { + "duration": { + "type": "integer", + "format": "int64", + "example": 60, + "description": "Duration of the event in minutes." + }, + "session_type": { "type": "string", - "example": "split weeks to assist rooming 29.06", - "description": "Describes what the booking is. Could contain a module code (for example WIBRG005) or just the type of activity (for example Lecture)." + "example": "L", + "description": "ID of the type of session, e.g. L = Lecture, PBL = Problem Based Learning. These come from UCL's internal database, and are provided in case a new session type that we are not aware of is in the timetable. See session_type_str below." }, - "roomname": { + "session_type_str": { "type": "string", - "example": "Torrington (1-19) 433", - "description": "The name of the room. It often includes the name of the site (building) as well." + "example": "Lecture", + "description": "Type of event such as Lecture, Problem Based Learning, Practical, etc. If the session_type has not been recognised by us then this will have the value Unknown." }, - "siteid": { + "session_group": { "type": "string", - "example": "005", - "description": "Every room is inside a site (building). All sites have IDs." + "example": "", + "description": "Used for lab groups, or other types of small group activity that does not involve the whole cohort. When the whole cohort is invited (e.g. lectures) this value is a blank string. In the personal timetable endpoint only the labs / group sessions assigned to the user with the OAuth token provided will be returned. For example, if the user is in LAB A then Labs B onwards will not be returned." + }, + "session_title": { + "type": "string", + "example": "Computational Complexity A", + "description": "The title of the event." }, "contact": { "type": "string", - "example": "Ms Leah Markwick", - "description": "The name of the person who made the booking. Substrings of the contact name can be used: Queries for Mark will include Mark Herbster. Sometimes, a society or student group may be the contact for a booking." + "example": "Prof Robin Hirsch", + "description": "The name associated with the individual room booking. This is the most likely candidate for the person taking the session or lecture. This name is also the most human-readable. Apps should display this value as the lecturer for any given booking, and only use the lecturer information given in the module{lecturer{}} dictionary to reference the course lead or owner." + } + } + }, + "module": { + "properties": { + "lecturer": { + "$ref": "#/components/schemas/lecturer" }, - "weeknumber": { - "type": "number", - "example": 1, - "description": "Timetabled week number." + "module_id": { + "type": "string", + "example": "COMP3004", + "description": "Module ID." }, - "roomid": { + "name": { "type": "string", - "example": "Z5", - "description": "The room ID (not to be confused with the roomname)." + "example": "Computational Complexity", + "description": "Module name." }, - "start_time": { + "department_id": { "type": "string", - "example": "2016-09-02T09:00:00+00:00", - "description": "Start time of the event." + "example": "COMPS_ENG", + "description": "Department code that this module comes under." }, - "phone": { + "department_name": { "type": "string", - "example": "45699", - "description": "Phone extension." + "example": "Computer Science", + "description": "Human readable department name that owns the module." } } }, - "equipment": { + "timetable": { "properties": { - "type": { + "date": { + "type": "array", + "items": { + "$ref": "#/components/schemas/event" + } + } + } + }, + "module_data_courses_modules": { + "properties": { + "module_id": { "type": "string", - "example": "FFF", - "description": "The type of equipment. Either Fixed Equipment (FE) or Fixed Feature (FF)." + "example": "COMP3004", + "description": "Module ID." }, - "description": { + "name": { "type": "string", - "example": "Managed PC", - "description": "What the piece of equipment actually is." + "example": "Computational Complexity", + "description": "Module name." }, - "units": { - "type": "number", - "example": 1, - "description": "The number of times this piece of equipment exists in the room." + "instances": { + "type": "array", + "items": { + "$ref": "#/components/schemas/instance" + } } } }, - "person": { + "instance": { "properties": { - "name": { + "full_module_id": { "type": "string", - "example": "Jane Doe", - "description": "The name of the person." + "example": "MATH--82-A7P-T2", + "description": "The module code concatenated with the instance data. This instance data is defined by the UCL Academic Model Project, and it is expanded out within this section." }, - "status": { - "type": "string", - "example": "Student", - "description": "Since only staff are returned through this API, this should always be Staff." + "class_size": { + "type": "number", + "example": 12, + "description": "The maximum number of students in the module permitted in that instance. In this example, twelve undergraduates are permitted to take this module in their third year, but ninety postgraduates may take the module." }, - "department": { - "type": "string", - "example": "Depet of Med Phys & Biomedical Eng", - "description": "The department the member of staff works under." + "delivery": { + "$ref": "#/components/schemas/delivery" }, - "email": { + "periods": { + "$ref": "#/components/schemas/period" + }, + "instance_code": { "type": "string", - "example": "jane.doe.17@ucl.ac.uk", - "description": "The email of the person." + "example": "A7P-T2", + "description": "A code that, when combined with a module code, forms the 'full_module_id' field above. This data is used to calculate the delivery and periods information that is also provided via JSON. Concatenating the module_id, a hyphen and the instance_code forms the full_module_id field." } } }, - "desktop_data": { + "delivery": { "properties": { - "room_status": { - "type": "string", - "example": "Room available all day. For accurate Library opening times, please check the Library Opening Hours website http://www.ucl.ac.uk/library/opening", - "description": "Some information about the room." + "fheq_level": { + "type": "integer", + "example": 7, + "description": "The level the course is taught at, and whether it is an undergraduate (true) or postgraduate (false) course." }, - "total_seats": { + "is_undergraduate": { + "type": "boolean", + "example": true, + "description": "Whether the course instance is for undergraduate (true) students or postgraduate (false) students." + }, + "student_type": { "type": "string", - "example": "35", - "description": "Total number of computers available in the room." + "example": "Campus-based, numeric mark scheme", + "description": "The type of student and assessment pattern available for that course. There are five options: 'Campus-based, numeric mark scheme', 'Campus-based, non-numeric mark scheme', 'Distance learner, numeric mark scheme', 'Distance learner, non-numeric mark scheme' and 'MBBS Resit'." + } + } + }, + "period": { + "properties": { + "teaching_periods": { + "$ref": "#/components/schemas/teaching_periods" }, - "location": { - "type": "object", - "properties": { - "latitude": { - "type": "string", - "example": "51.523481", - "description": "Latitude of the location of the site." - }, - "room_id": { - "type": "string", - "example": "C14", - "description": "Room ID." - }, - "postcode": { - "type": "string", - "example": "WC1E 6BT", - "description": "Postcode of the location of the room." - }, - "address": { - "type": "string", - "example": "Malet Place, Gower Street", - "description": "Address of the room" - }, - "room_name": { - "type": "string", - "example": "Ground-Ground floor - Public", - "description": "Name of the room." - }, - "building_name": { - "type": "string", - "example": "DMS Watson Science Library", - "description": "Name of the building." - }, - "longitude": { - "type": "string", - "example": "-0.132571", - "description": "Longitude of the location of the site." - } - } + "year_long": { + "type": "boolean", + "example": false, + "description": "Whether the course is timetabled to last for an entire academic year." }, - "free_seats": { - "type": "string", - "example": "28", - "description": "Number of free seats in the room." + "lsr": { + "type": "boolean", + "example": false, + "description": "Whether the module is timetabled during the Late Summer Resit period. This is used internally by Examinations to timetable Late Summer Assessments (LSAs)." + }, + "summer_school": { + "$ref": "#/components/schemas/summer_school" } } }, - "survey": { + "teaching_periods": { "properties": { - "id": { - "type": "number", - "example": 46, - "description": "The library survey's ID. This is used later to identify individual libraries." - }, - "name": { - "type": "string", - "example": "UCL Institute of Education Library", - "description": "The human-readable name of the library." + "term_1": { + "type": "boolean", + "example": false, + "description": "Whether the course is taught during Term 1." }, - "active": { + "term_2": { "type": "boolean", "example": true, - "description": "Whether the survey is active and working." - }, - "start_time": { - "type": "string", - "example": "09:00", - "description": "Standard UCL opening time supplied by the backend. This field should NOT be trusted as information on when a particular library is open. This is usually set to 09:00." + "description": "Whether the course is taught during Term 2." }, - "end_time": { - "type": "string", - "example": "17:00", - "description": "Standard UCL closing time supplied by the backend. This field should NOT be trusted as information on when a particular library closes. This is usually set to 17:00." + "term_3": { + "type": "boolean", + "example": false, + "description": "Whether the course is taught during Term 3." }, - "staff_survey": { + "term_1_next_year": { "type": "boolean", - "example": true, - "description": "Whether the survey represents a staff workspace (`true`) or a student work or study space (`false`). This is useful in apps where you set the `survey_filter` parameter to `all` and wish to do filtering of student and staff workspaces in your app or API as opposed to leaving the filtering to UCL API. By default, as `survey_filter` is set to `student` unless you specify otherwise, all workspaces will have this parameter set to `false`." + "example": false, + "description": "Whether the course is taught during Term 1 of the following academic year. This is used by admissions to calculate the end dates for non-standard programmes, and therefore is rare." }, - "maps": { - "type": "array", - "description": "List of maps corresponding to regions within the library's survey.", - "items": { - "$ref": "#/components/schemas/map" - } + "summer": { + "type": "boolean", + "example": false, + "description": "Whether the course timetabled during the summer holidays. This can happen in some Postgraduate and Medicine teaching arrangements, but is rare. Note that this is NOT the same as the UCL Summer School." + } + } + }, + "summer_school": { + "properties": { + "is_summer_school": { + "type": "boolean", + "example": false, + "description": "Whether the module is taught as part of the UCL Summer School (true) or standard academic teaching (false)." }, - "location": { + "sessions": { "type": "object", "properties": { - "coordinates": { - "type": "object", - "description": "Object containing a latitude and longitude.", - "properties": { - "lat": { - "type": "string", - "example": "51.522897", - "description": "Latitude of the survey location." - }, - "lng": { - "type": "string", - "example": "-0.127864", - "description": "Longitude of the survey location." - } - } + "session_1": { + "type": "boolean", + "example": false, + "description": "Whether the module is taught in the first summer school session of this academic year's summer. This will be false for all standard academic modules." }, - "address": { - "type": "array", - "items": { - "type": "string" - }, - "example": [ - "Newsam Library and Archives", - "20 Bedford Way", - "London", - "WC1H 0AL" - ], - "description": "List containing address lines for the survey location." + "session_2": { + "type": "boolean", + "example": false, + "description": "Whether the module is taught in the second summer school session of this academic year's summer. This will be false for all standard academic modules." } } } } }, - "map": { + "lecturer": { "properties": { - "id": { - "type": "number", - "example": 114, - "description": "The map's ID." - }, "name": { "type": "string", - "example": "Level 4", - "description": "The name of the mapped section of the library's survey, such as a level, room or wing." + "example": "HUNTER, Anthony (Prof)", + "description": "Name of lecturer" }, - "image_id": { - "type": "integer", - "example": 123, - "description": "The ID of the map's image. This can be used to download a CAD drawing of the map." + "department_name": { + "type": "string", + "example": "Computer Science", + "description": "Human readable department name that owns the module." + }, + "department_id": { + "type": "string", + "example": "COMPS_ENG", + "description": "Department code that this module comes under." + }, + "email": { + "type": "string", + "example": "ucachun@ucl.ac.uk", + "description": "Email address for lecturer" } } }, - "map_with_sensors": { + "location": { "properties": { - "id": { - "type": "integer", - "example": 73, - "description": "The map's ID." - }, "name": { "type": "string", - "example": "Level 3", - "description": "The name of the mapped section of the library's survey, such as a level, room or wing." + "example": "Roberts Building 421", + "description": "Room name of the timetable event." }, - "image_id": { + "address": { + "type": "array", + "minItems": 4, + "maxItems": 4, + "items": { + "type": "string" + }, + "example": [ + "Torrington Place", + "London", + "WC1E 7JE" + ], + "description": "Address represented as an array." + }, + "site_name": { + "type": "string", + "example": "Roberts Building", + "description": "Name of the site / building where the event is happening." + }, + "type": { + "type": "string", + "example": "CB", + "description": "Type of the room eg., Centrally Bookable (CB) or Departmentally Bookable (DB)." + }, + "capacity": { "type": "integer", - "example": 79, - "description": "The ID of the map's image. This can be used to download a CAD drawing of the map." + "example": 94, + "description": "Capacity of the room (e.g. how many seats are in a lecture theatre, or how many can be sat at tables in a flat space)." }, - "sensors": { + "coordinates": { "type": "object", - "additionalProperties": { - "$ref": "#/components/schemas/sensor" + "properties": { + "lat": { + "type": "string", + "example": "51.524699", + "description": "Latitude of location" + }, + "lng": { + "type": "string", + "example": "-0.13366", + "description": "Longitude of location" + } } } } }, - "sensor": { + "department": { "properties": { - "description_2": { - "type": "string", - "example": "", - "description": "Description 2." - }, - "floor": { - "type": "string", - "example": "False", - "description": "Whether the device is on the floor" - }, - "y_pos": { + "department_id": { "type": "string", - "example": "14893.0", - "description": "The Y coordinate position of the sensor on the map." + "example": "COMPS_ENG", + "description": "Department code." }, - "description_3": { + "name": { "type": "string", - "example": "", - "description": "Description 3." - }, - "device_type": { + "example": "Computer Science", + "description": "Human readable department name." + } + } + }, + "course": { + "properties": { + "course_name": { "type": "string", - "example": "Desk", - "description": "Type of seat. Usually this is Desk." + "example": "MRes Computational Statistics and Machine Learning", + "description": "The human readable name for the module." }, - "host_address": { + "course_id": { "type": "string", - "example": "584", - "description": "Address of host." + "example": "TMRCOMSSML01", + "description": "The module code." }, - "building_name": { + "years": { + "type": "integer", + "example": 1, + "description": "Length of the course given in years." + } + } + }, + "room": { + "properties": { + "roomname": { "type": "string", - "example": "IOE (20 B-Way)", - "description": "A short but human-readable name of the building that the sensor is in." + "example": "Wilkins Building (Main Building) Portico", + "description": "The name of the room. It often includes the name of the site (building) as well." }, - "room_description": { + "roomid": { "type": "string", - "example": "", - "description": "A short but human-readable name of the room that the sensor is in." + "example": "Z4", + "description": "The room ID (not to be confused with the roomname)." }, - "last_trigger_type": { + "siteid": { "type": "string", - "example": "Occupied", - "description": "The last event the sensor recorded. Possible known values are Absent and Occupied, but this is not guaranteed. NB: only returned when return_states=true." + "example": "005", + "description": "Every room is inside a site (building). All sites have IDs." }, - "survey_id": { + "sitename": { "type": "string", - "example": "46", - "description": "The ID of the library/survey that was requested in the query parameter." + "example": "Main Building", + "description": "Every site (building) has a name. In some cases this is contained in the roomname as well." }, - "room_type": { + "capacity": { + "type": "integer", + "example": 50, + "description": "Every room has a set capacity of how many people can fit inside it. When supplied, all rooms with the given capacity or greater will be returned." + }, + "classification": { "type": "string", - "example": "Open Plan", - "description": "The type of the room." + "example": "SS", + "description": "The room type ID." }, - "room_name": { + "classification_name": { "type": "string", - "example": "324", - "description": "The name of the room." + "example": "Social Space", + "description": "A human-readable version of the room type. AN = Anechoic Chamber, CI = Clinic Room, CF = Catering Facilities CFE = Cafe, CL = Cloakroom, CR = Classroom, ER = Equipment Room, IN = Installation, LA = Laboratory, LB = Library, LT = Lecture Theatre, MR = Meeting Room, OF = Office, PC1 = Public Cluster, PC2 = Public Cluster - Tutorial, PC3 = Public Cluster - Students, RC = Reverberation Chamber, SS = Social Space, STU = Studio, TH = Theatre. If the room type is unknown, this value will be set to 'Unknown Room Type'." }, - "room_id": { + "automated": { "type": "string", - "example": "291", - "description": "The ID of the room." + "example": "N", + "description": "Whether bookings in this room will be confirmed automatically. A stands for automated, and N for not automated. P represents that the confirmation will be automatic, but only under certain circumstances." }, "location": { - "type": "string", - "example": "", - "description": "The location of this sensor." + "type": "object", + "properties": { + "address": { + "type": "array", + "minItems": 4, + "maxItems": 4, + "items": { + "type": "string" + }, + "example": [ + "Gower Street", + "London", + "WC1E 6BT" + ], + "description": "Address represented as an array." + }, + "coordinates": { + "type": "object", + "properties": { + "lat": { + "type": "string", + "example": "51.524699", + "description": "Latitude of location" + }, + "lng": { + "type": "string", + "example": "-0.13366", + "description": "Longitude of location" + } + } + } + } + } + } + }, + "booking": { + "properties": { + "slotid": { + "type": "number", + "format": "int64", + "example": 998503, + "description": "Slot ID." }, - "survey_device_id": { + "end_time": { "type": "string", - "example": "8420", - "description": "The ID of this survey device." + "example": "2016-09-02T18:00:00+00:00", + "description": "End time of the event." }, - "share_id": { + "description": { "type": "string", - "example": "None", - "description": "The Share ID." + "example": "split weeks to assist rooming 29.06", + "description": "Describes what the booking is. Could contain a module code (for example WIBRG005) or just the type of activity (for example Lecture)." }, - "x_pos": { + "roomname": { "type": "string", - "example": "32432.0", - "description": "The X coordinate position of the sensor on the map." + "example": "Torrington (1-19) 433", + "description": "The name of the room. It often includes the name of the site (building) as well." }, - "description_1": { + "siteid": { "type": "string", - "example": "Description 1." + "example": "005", + "description": "Every room is inside a site (building). All sites have IDs." }, - "hardware_id": { + "contact": { "type": "string", - "example": "584001", - "description": "A unique ID for the sensor." + "example": "Ms Leah Markwick", + "description": "The name of the person who made the booking. Substrings of the contact name can be used: Queries for Mark will include Mark Herbster. Sometimes, a society or student group may be the contact for a booking." }, - "pir_address": { - "type": "string", - "example": "1", - "description": "PIR address." + "weeknumber": { + "type": "number", + "example": 1, + "description": "Timetabled week number." }, - "last_trigger_timestamp": { + "roomid": { "type": "string", - "example": "2018-02-15T22:42:28+00:00", - "description": "The last time that this sensor's update value was recorded. NB: only returned when return_states=true." - }, - "occupied": { - "type": "boolean", - "example": true, - "description": "Whether the seat is occupied or not. This takes into account UCL's thirty minute rule, so it's possible that the seat could have been marked as absent a few minutes ago, but this value is still set to true, as UCL allows students to leave their seat unattended for up to thirty minutes at a time (e.g. to use the bathroom or get food). Integrations that provide live seating information to students should use this value so as to have parity with the UCL Library seating policy and the UCL Library website. NB: only returned when return_states=true." - } - } - }, - "sensor_average_survey": { - "properties": { - "survey_id": { - "type": "integer", - "example": 46, - "description": "The ID of the library/survey that was requested in the query parameter." + "example": "Z5", + "description": "The room ID (not to be confused with the roomname)." }, - "name": { + "start_time": { "type": "string", - "example": "UCL Institute of Education Library", - "description": "Name of survey location." - }, - "averages": { - "type": "object", - "additionalProperties": { - "$ref": "#/components/schemas/average" - } - } - } - }, - "historical_survey_data": { - "properties": { - "sensor_id": { - "type": "integer", - "example": 20520001, - "description": "The ID of the sensor." + "example": "2016-09-02T09:00:00+00:00", + "description": "Start time of the event." }, - "datetime": { + "phone": { "type": "string", - "example": "2020-01-16T14:20:00", - "description": "The datetime of the sensor changing state." - }, - "averages": { - "type": "integer", - "example": 1, - "description": "The state of the sensor (1=occupied; 0=absent; -1=unknown)" + "example": "45699", + "description": "Phone extension." } } }, - "historical_sensor": { + "equipment": { "properties": { - "survey_id": { - "type": "integer", - "example": 4, - "description": "The ID of the survey location." - }, - "sensor_id": { - "type": "integer", - "example": 20520001, - "description": "The ID of the sensor." + "type": { + "type": "string", + "example": "FFF", + "description": "The type of equipment. Either Fixed Equipment (FE) or Fixed Feature (FF)." }, - "hardware_id": { - "type": "integer", - "example": 520001, - "description": "The hardware ID of the sensor." + "description": { + "type": "string", + "example": "Managed PC", + "description": "What the piece of equipment actually is." }, - "survey_device_id": { - "type": "integer", + "units": { + "type": "number", "example": 1, - "description": "The survey device ID of the sensor." + "description": "The number of times this piece of equipment exists in the room." } } }, - "historical_survey": { + "person": { "properties": { - "survey_id": { - "type": "integer", - "example": 4, - "description": "The ID of the survey location." - }, "name": { "type": "string", - "example": "Bedford Way LG16", - "description": "The name of the survey location" + "example": "Jane Doe", + "description": "The name of the person." }, - "start_datetime": { + "status": { "type": "string", - "example": "2019-07-06T08:00:00", - "description": "The start datetime of the survey location." + "example": "Student", + "description": "Since only staff are returned through this API, this should always be Staff." }, - "end_datetime": { + "department": { "type": "string", - "example": "2030-12-31T20:00:00", - "description": "The end datetime of the survey location." - }, - "active": { - "type": "boolean", - "example": true, - "description": "If the survey location is currently active (i.e., collecting new data)." + "example": "Depet of Med Phys & Biomedical Eng", + "description": "The department the member of staff works under." }, - "last_updated": { + "email": { "type": "string", - "example": "2020-01-02T02:00:00", - "description": "The last time this survey location was updated." + "example": "jane.doe.17@ucl.ac.uk", + "description": "The email of the person." } } }, - "average": { + "desktop_data": { "properties": { - "sensors_absent": { - "type": "integer", - "example": 291, - "description": "The average number of free seats at time t." - }, - "sensors_total": { - "type": "integer", - "example": 324, - "description": "The total number of used seats at time t." - }, - "sensors_occupied": { - "type": "integer", - "example": 33, - "description": "The average number of used seats at time t." - } - } - }, - "average_with_name_and_id": { - "properties": { - "sensors_absent": { - "type": "integer", - "example": 47, - "description": "Number of free seats in that section of the library." + "room_status": { + "type": "string", + "example": "Room available all day. For accurate Library opening times, please check the Library Opening Hours website http://www.ucl.ac.uk/library/opening", + "description": "Some information about the room." }, - "sensors_total": { - "type": "integer", - "example": 50, - "description": "The total number of used seats at time t." + "total_seats": { + "type": "string", + "example": "35", + "description": "Total number of computers available in the room." }, - "sensors_occupied": { - "type": "integer", - "example": 3, - "description": "Number of taken / occupied seats in that section of the library." + "location": { + "type": "object", + "properties": { + "latitude": { + "type": "string", + "example": "51.523481", + "description": "Latitude of the location of the site." + }, + "room_id": { + "type": "string", + "example": "C14", + "description": "Room ID." + }, + "postcode": { + "type": "string", + "example": "WC1E 6BT", + "description": "Postcode of the location of the room." + }, + "address": { + "type": "string", + "example": "Malet Place, Gower Street", + "description": "Address of the room" + }, + "room_name": { + "type": "string", + "example": "Ground-Ground floor - Public", + "description": "Name of the room." + }, + "building_name": { + "type": "string", + "example": "DMS Watson Science Library", + "description": "Name of the building." + }, + "longitude": { + "type": "string", + "example": "-0.132571", + "description": "Longitude of the location of the site." + } + } }, - "name": { + "free_seats": { "type": "string", - "example": "Open Area", - "description": "The name of the survey (library)." - }, - "id": { - "type": "integer", - "example": 72, - "description": "ID of the library region (map)." + "example": "28", + "description": "Number of free seats in the room." } } }, - "survey_with_maps": { + "survey": { "properties": { + "id": { + "type": "number", + "example": 46, + "description": "The library survey's ID. This is used later to identify individual libraries." + }, "name": { "type": "string", - "example": "Teaching Rooms", - "description": "Name of the library region (map)." + "example": "UCL Institute of Education Library", + "description": "The human-readable name of the library." }, - "id": { - "type": "integer", - "example": 73, - "description": "ID of the library region (map)." + "active": { + "type": "boolean", + "example": true, + "description": "Whether the survey is active and working." }, - "sensors_absent": { - "type": "integer", - "example": 72, - "description": "Number of free seats in that section of the library." + "start_time": { + "type": "string", + "example": "09:00", + "description": "Standard UCL opening time supplied by the backend. This field should NOT be trusted as information on when a particular library is open. This is usually set to 09:00." }, - "sensors_total": { - "type": "integer", - "example": 80, - "description": "The total number of used seats at time t." + "end_time": { + "type": "string", + "example": "17:00", + "description": "Standard UCL closing time supplied by the backend. This field should NOT be trusted as information on when a particular library closes. This is usually set to 17:00." }, - "sensors_occupied": { - "type": "integer", - "example": 3, - "description": "Number of taken / occupied seats in that section of the library." + "staff_survey": { + "type": "boolean", + "example": true, + "description": "Whether the survey represents a staff workspace (`true`) or a student work or study space (`false`). This is useful in apps where you set the `survey_filter` parameter to `all` and wish to do filtering of student and staff workspaces in your app or API as opposed to leaving the filtering to UCL API. By default, as `survey_filter` is set to `student` unless you specify otherwise, all workspaces will have this parameter set to `false`." }, "maps": { "type": "array", + "description": "List of maps corresponding to regions within the library's survey.", "items": { - "$ref": "#/components/schemas/average_with_name_and_id" - } - } - } - }, - "svg": { - "type": "object", - "properties": { - "xmlns:ev": { - "type": "string", - "example": "http://www.w3.org/2001/xml-events", - "xml": { - "attribute": true - } - }, - "xmlns:xlink": { - "type": "string", - "example": "http://www.w3.org/1999/xlink", - "xml": { - "attribute": true - } - }, - "xmlns": { - "type": "string", - "example": "http://www.w3.org/2000/svg", - "xml": { - "attribute": true + "$ref": "#/components/schemas/map" } }, - "g": { + "location": { "type": "object", "properties": { - "transform": { - "type": "string", - "example": "scale(0.02, 0.02)", - "xml": { - "attribute": true - } - }, - "image": { + "coordinates": { "type": "object", + "description": "Object containing a latitude and longitude.", "properties": { - "width": { - "type": "string", - "example": "28329.0", - "xml": { - "attribute": true - } - }, - "height": { + "lat": { "type": "string", - "example": "29882.0", - "xml": { - "attribute": true - } + "example": "51.522897", + "description": "Latitude of the survey location." }, - "xlink:href": { + "lng": { "type": "string", - "example": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAA7QAAA...", - "xml": { - "attribute": true - } - }, - "g": { - "type": "array", - "items": { - "$ref": "#/components/schemas/seat_image" - } + "example": "-0.127864", + "description": "Longitude of the survey location." } } + }, + "address": { + "type": "array", + "items": { + "type": "string" + }, + "example": [ + "Newsam Library and Archives", + "20 Bedford Way", + "London", + "WC1H 0AL" + ], + "description": "List containing address lines for the survey location." } } } } }, - "seat_image": { - "type": "object", + "map": { "properties": { - "transform": { + "id": { + "type": "number", + "example": 114, + "description": "The map's ID." + }, + "name": { "type": "string", - "example": "translate(13223.0,26708.0)", - "xml": { - "attribute": true - } + "example": "Level 4", + "description": "The name of the mapped section of the library's survey, such as a level, room or wing." }, - "circle": { - "type": "object", - "properties": { - "r": { - "type": "string", - "example": "128", - "xml": { - "attribute": true - } - }, - "fill": { - "type": "string", - "example": "#B60202", - "xml": { - "attribute": true - } - } - } + "image_id": { + "type": "integer", + "example": 123, + "description": "The ID of the map's image. This can be used to download a CAD drawing of the map." } } }, - "error": { - "type": "object", + "map_with_sensors": { "properties": { - "ok": { - "type": "boolean", - "default": false + "id": { + "type": "integer", + "example": 73, + "description": "The map's ID." }, - "error": { - "type": "string" + "name": { + "type": "string", + "example": "Level 3", + "description": "The name of the mapped section of the library's survey, such as a level, room or wing." + }, + "image_id": { + "type": "integer", + "example": 79, + "description": "The ID of the map's image. This can be used to download a CAD drawing of the map." + }, + "sensors": { + "type": "object", + "additionalProperties": { + "$ref": "#/components/schemas/sensor" + } } } - } - }, - "examples": { - "ErrorNoToken": { - "value": { - "ok": false, - "error": "No token provided." - }, - "summary": "No token provided" }, - "ErrorInvalidToken": { - "value": { - "ok": false, - "error": "Token is invalid." - }, - "summary": "Invalid token" - }, - "ErrorTokenNotExist": { - "value": { - "ok": false, - "error": "Token does not exist." - }, - "summary": "Non-existent token" - }, - "ErrorNoClientSecret": { - "value": { - "ok": false, - "error": "No Client Secret provided." - }, - "summary": "No Client Secret provided" - }, - "ErrorInvalidClientSecret": { - "value": { - "ok": false, - "error": "Client secret incorrect." - }, - "summary": "Client secret incorrect" - }, - "ErrorThrottling": { - "value": { - "ok": false, - "error": "You have been throttled. Please try again in 10 seconds." - }, - "summary": "Throttling" + "sensor": { + "properties": { + "description_2": { + "type": "string", + "example": "", + "description": "Description 2." + }, + "floor": { + "type": "string", + "example": "False", + "description": "Whether the device is on the floor" + }, + "y_pos": { + "type": "string", + "example": "14893.0", + "description": "The Y coordinate position of the sensor on the map." + }, + "description_3": { + "type": "string", + "example": "", + "description": "Description 3." + }, + "device_type": { + "type": "string", + "example": "Desk", + "description": "Type of seat. Usually this is Desk." + }, + "host_address": { + "type": "string", + "example": "584", + "description": "Address of host." + }, + "building_name": { + "type": "string", + "example": "IOE (20 B-Way)", + "description": "A short but human-readable name of the building that the sensor is in." + }, + "room_description": { + "type": "string", + "example": "", + "description": "A short but human-readable name of the room that the sensor is in." + }, + "last_trigger_type": { + "type": "string", + "example": "Occupied", + "description": "The last event the sensor recorded. Possible known values are Absent and Occupied, but this is not guaranteed. NB: only returned when return_states=true." + }, + "survey_id": { + "type": "string", + "example": "46", + "description": "The ID of the library/survey that was requested in the query parameter." + }, + "room_type": { + "type": "string", + "example": "Open Plan", + "description": "The type of the room." + }, + "room_name": { + "type": "string", + "example": "324", + "description": "The name of the room." + }, + "room_id": { + "type": "string", + "example": "291", + "description": "The ID of the room." + }, + "location": { + "type": "string", + "example": "", + "description": "The location of this sensor." + }, + "survey_device_id": { + "type": "string", + "example": "8420", + "description": "The ID of this survey device." + }, + "share_id": { + "type": "string", + "example": "None", + "description": "The Share ID." + }, + "x_pos": { + "type": "string", + "example": "32432.0", + "description": "The X coordinate position of the sensor on the map." + }, + "description_1": { + "type": "string", + "example": "Description 1." + }, + "hardware_id": { + "type": "string", + "example": "584001", + "description": "A unique ID for the sensor." + }, + "pir_address": { + "type": "string", + "example": "1", + "description": "PIR address." + }, + "last_trigger_timestamp": { + "type": "string", + "example": "2018-02-15T22:42:28+00:00", + "description": "The last time that this sensor's update value was recorded. NB: only returned when return_states=true." + }, + "occupied": { + "type": "boolean", + "example": true, + "description": "Whether the seat is occupied or not. This takes into account UCL's thirty minute rule, so it's possible that the seat could have been marked as absent a few minutes ago, but this value is still set to true, as UCL allows students to leave their seat unattended for up to thirty minutes at a time (e.g. to use the bathroom or get food). Integrations that provide live seating information to students should use this value so as to have parity with the UCL Library seating policy and the UCL Library website. NB: only returned when return_states=true." + } + } }, - "ErrorInactiveToken": { - "value": { - "ok": false, - "error": "The token is inactive as the user has revoked your app's access to their data." - }, - "summary": "Inactive token" + "sensor_average_survey": { + "properties": { + "survey_id": { + "type": "integer", + "example": 46, + "description": "The ID of the library/survey that was requested in the query parameter." + }, + "name": { + "type": "string", + "example": "UCL Institute of Education Library", + "description": "Name of survey location." + }, + "averages": { + "type": "object", + "additionalProperties": { + "$ref": "#/components/schemas/average" + } + } + } }, - "ErrorRejectedScope": { - "value": { - "ok": false, - "error": "The token provided does not have permission to access this data." - }, - "summary": "Weak token scope" + "historical_survey_data": { + "properties": { + "sensor_id": { + "type": "integer", + "example": 20520001, + "description": "The ID of the sensor." + }, + "datetime": { + "type": "string", + "example": "2020-01-16T14:20:00", + "description": "The datetime of the sensor changing state." + }, + "averages": { + "type": "integer", + "example": 1, + "description": "The state of the sensor (1=occupied; 0=absent; -1=unknown)" + } + } }, - "ErrorPersonalData": { - "value": { - "ok": false, - "error": "Personal data requires OAuth." - }, - "summary": "OAuth required" + "historical_sensor": { + "properties": { + "survey_id": { + "type": "integer", + "example": 4, + "description": "The ID of the survey location." + }, + "sensor_id": { + "type": "integer", + "example": 20520001, + "description": "The ID of the sensor." + }, + "hardware_id": { + "type": "integer", + "example": 520001, + "description": "The hardware ID of the sensor." + }, + "survey_device_id": { + "type": "integer", + "example": 1, + "description": "The survey device ID of the sensor." + } + } }, - "ErrorTempTokenInvalid": { + "historical_survey": { + "properties": { + "survey_id": { + "type": "integer", + "example": 4, + "description": "The ID of the survey location." + }, + "name": { + "type": "string", + "example": "Bedford Way LG16", + "description": "The name of the survey location" + }, + "start_datetime": { + "type": "string", + "example": "2019-07-06T08:00:00", + "description": "The start datetime of the survey location." + }, + "end_datetime": { + "type": "string", + "example": "2030-12-31T20:00:00", + "description": "The end datetime of the survey location." + }, + "active": { + "type": "boolean", + "example": true, + "description": "If the survey location is currently active (i.e., collecting new data)." + }, + "last_updated": { + "type": "string", + "example": "2020-01-02T02:00:00", + "description": "The last time this survey location was updated." + } + } + }, + "average": { + "properties": { + "sensors_absent": { + "type": "integer", + "example": 291, + "description": "The average number of free seats at time t." + }, + "sensors_total": { + "type": "integer", + "example": 324, + "description": "The total number of used seats at time t." + }, + "sensors_occupied": { + "type": "integer", + "example": 33, + "description": "The average number of used seats at time t." + } + } + }, + "average_with_name_and_id": { + "properties": { + "sensors_absent": { + "type": "integer", + "example": 47, + "description": "Number of free seats in that section of the library." + }, + "sensors_total": { + "type": "integer", + "example": 50, + "description": "The total number of used seats at time t." + }, + "sensors_occupied": { + "type": "integer", + "example": 3, + "description": "Number of taken / occupied seats in that section of the library." + }, + "name": { + "type": "string", + "example": "Open Area", + "description": "The name of the survey (library)." + }, + "id": { + "type": "integer", + "example": 72, + "description": "ID of the library region (map)." + } + } + }, + "survey_with_maps": { + "properties": { + "name": { + "type": "string", + "example": "Teaching Rooms", + "description": "Name of the library region (map)." + }, + "id": { + "type": "integer", + "example": 73, + "description": "ID of the library region (map)." + }, + "sensors_absent": { + "type": "integer", + "example": 72, + "description": "Number of free seats in that section of the library." + }, + "sensors_total": { + "type": "integer", + "example": 80, + "description": "The total number of used seats at time t." + }, + "sensors_occupied": { + "type": "integer", + "example": 3, + "description": "Number of taken / occupied seats in that section of the library." + }, + "maps": { + "type": "array", + "items": { + "$ref": "#/components/schemas/average_with_name_and_id" + } + } + } + }, + "svg": { + "type": "object", + "properties": { + "xmlns:ev": { + "type": "string", + "example": "http://www.w3.org/2001/xml-events", + "xml": { + "attribute": true + } + }, + "xmlns:xlink": { + "type": "string", + "example": "http://www.w3.org/1999/xlink", + "xml": { + "attribute": true + } + }, + "xmlns": { + "type": "string", + "example": "http://www.w3.org/2000/svg", + "xml": { + "attribute": true + } + }, + "g": { + "type": "object", + "properties": { + "transform": { + "type": "string", + "example": "scale(0.02, 0.02)", + "xml": { + "attribute": true + } + }, + "image": { + "type": "object", + "properties": { + "width": { + "type": "string", + "example": "28329.0", + "xml": { + "attribute": true + } + }, + "height": { + "type": "string", + "example": "29882.0", + "xml": { + "attribute": true + } + }, + "xlink:href": { + "type": "string", + "example": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAA7QAAA...", + "xml": { + "attribute": true + } + }, + "g": { + "type": "array", + "items": { + "$ref": "#/components/schemas/seat_image" + } + } + } + } + } + } + } + }, + "seat_image": { + "type": "object", + "properties": { + "transform": { + "type": "string", + "example": "translate(13223.0,26708.0)", + "xml": { + "attribute": true + } + }, + "circle": { + "type": "object", + "properties": { + "r": { + "type": "string", + "example": "128", + "xml": { + "attribute": true + } + }, + "fill": { + "type": "string", + "example": "#B60202", + "xml": { + "attribute": true + } + } + } + } + } + }, + "error": { + "type": "object", + "properties": { + "ok": { + "type": "boolean", + "default": false + }, + "error": { + "type": "string" + } + } + } + }, + "examples": { + "ErrorNoToken": { "value": { "ok": false, - "error": "Temporary token in either invalid or expired." + "error": "No token provided." }, - "summary": "Temporary token expired" + "summary": "No token provided" }, - "ErrorTempTokenInvalidUse": { + "ErrorInvalidToken": { "value": { "ok": false, - "error": "Temporary token can only be used for /bookings." + "error": "Token is invalid." }, - "summary": "Temporary token invalid usage" + "summary": "Invalid token" }, - "ErrorTempTokenLimit": { + "ErrorTokenNotExist": { "value": { "ok": false, - "error": "Temporary token can only return one booking." + "error": "Token does not exist." }, - "summary": "Temporary token bookings limit" - } - }, - "responses": { - "NotFound": { - "description": "Entity not found." + "summary": "Non-existent token" }, - "IllegalInput": { + "ErrorNoClientSecret": { + "value": { + "ok": false, + "error": "No Client Secret provided." + }, + "summary": "No Client Secret provided" + }, + "ErrorInvalidClientSecret": { + "value": { + "ok": false, + "error": "Client secret incorrect." + }, + "summary": "Client secret incorrect" + }, + "ErrorThrottling": { + "value": { + "ok": false, + "error": "You have been throttled. Please try again in 10 seconds." + }, + "summary": "Throttling" + }, + "ErrorInactiveToken": { + "value": { + "ok": false, + "error": "The token is inactive as the user has revoked your app's access to their data." + }, + "summary": "Inactive token" + }, + "ErrorRejectedScope": { + "value": { + "ok": false, + "error": "The token provided does not have permission to access this data." + }, + "summary": "Weak token scope" + }, + "ErrorPersonalData": { + "value": { + "ok": false, + "error": "Personal data requires OAuth." + }, + "summary": "OAuth required" + }, + "ErrorTempTokenInvalid": { + "value": { + "ok": false, + "error": "Temporary token in either invalid or expired." + }, + "summary": "Temporary token expired" + }, + "ErrorTempTokenInvalidUse": { + "value": { + "ok": false, + "error": "Temporary token can only be used for /bookings." + }, + "summary": "Temporary token invalid usage" + }, + "ErrorTempTokenLimit": { + "value": { + "ok": false, + "error": "Temporary token can only return one booking." + }, + "summary": "Temporary token bookings limit" + }, + "ErrorLibCalOAuthTokenInvalid": { + "value": { + "ok": false, + "error": "Unable to refresh LibCal OAuth token" + }, + "summary": "LibCal service unavailable" + }, + "ErrorLibCalOAuth": { + "value": { + "ok": false, + "error": "Personal data requires OAuth." + } + }, + "ErrorLibCalNoBookingsDeleted": { + "value": { + "ok": false, + "error": "No bookings were found and so no bookings were deleted" + } + } + }, + "responses": { + "NotFound": { + "description": "Entity not found." + }, + "IllegalInput": { "description": "Illegal input for operation." } }, "securitySchemes": { + "ApiToken": { + "type": "apiKey", + "description": "This API requires you to pass your API key as a query parameter called 'token'.", + "name": "token", + "in": "query" + }, "OAuthToken": { "type": "apiKey", - "description": "This API requires you to pass your OAuth2 token as a query parameter called 'token'. Use the /authorize and /oauth/token endpoints to authorize a user and get this token.", + "description": "This API requires you to pass your OAuth2 token as a query parameter called 'token'. Use the /authorise and /oauth/token endpoints to authorize a user and get this token.", "name": "token", "in": "query" }, "OAuthSecurity": { "type": "oauth2", - "description": "This API uses OAuth2 with the implicit grant flow. [More info](https://uclapi.com/docs#OAuthSecurity)", + "description": "This API uses OAuth2 with the authorization code flow. [More info](https://uclapi.com/docs#OAuthSecurity)", "flows": { "authorizationCode": { - "authorizationUrl": "/authorise", - "tokenUrl": "/token", + "authorizationUrl": "/oauth/authorise", + "tokenUrl": "/oauth/token", "scopes": { "personal_timetable": "read user's timetable", - "student_number": "read user's student number" + "student_number": "read user's student number", + "libcal_read": "read user's LibCal bookings", + "libcal_write": "reserve/cancel user's LibCal bookings" + } + } + } + } + } + }, + "paths": { + "/timetable/personal": { + "get": { + "summary": "Returns the personal timetable of the user.", + "tags": [ + "Timetable" + ], + "security": [ + { + "OAuthSecurity": [ + "personal_timetable" + ], + "OAuthToken": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/client_secret" + }, + { + "name": "date", + "in": "query", + "description": "A date to filter entries by", + "required": false, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "A timetable.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "timetable": { + "$ref": "#/components/schemas/timetable" + }, + "ok": { + "type": "boolean" + } + } + } + } + } + }, + "403": { + "description": "Permission error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/error" + }, + "examples": { + "1": { + "$ref": "#/components/examples/ErrorRejectedScope" + } + } + } + } + }, + "400": { + "description": "Request error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/error" + }, + "examples": { + "1": { + "$ref": "#/components/examples/ErrorNoToken" + }, + "2": { + "$ref": "#/components/examples/ErrorTokenNotExist" + }, + "3": { + "$ref": "#/components/examples/ErrorInvalidToken" + }, + "4": { + "$ref": "#/components/examples/ErrorThrottling" + }, + "5": { + "$ref": "#/components/examples/ErrorNoClientSecret" + }, + "6": { + "$ref": "#/components/examples/ErrorInvalidClientSecret" + }, + "7": { + "$ref": "#/components/examples/ErrorInactiveToken" + }, + "8": { + "$ref": "#/components/examples/ErrorPersonalData" + } + } + } + } + } + } + } + }, + "/timetable/bymodule": { + "get": { + "summary": "Returns a yearly timetable for the supplied modules.", + "tags": [ + "Timetable" + ], + "security": [ + { + "OAuthSecurity": [], + "OAuthToken": [] + } + ], + "parameters": [ + { + "name": "modules", + "in": "query", + "description": "A comma-separated list of the module codes you want the timetable of. You can supply either standard module codes (e.g. COMP0133), or full codes including the instance of the module (COMP0133-A7U-T1). Note that if you do not supply an instance, every single timetable entry will be returned including duplicates for the same module taught as multiple instances. It is recommended that a full module code including instance be supplied.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "date", + "in": "query", + "description": "A date to filter entries by", + "required": false, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "A timetable.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "timetable": { + "$ref": "#/components/schemas/timetable" + }, + "ok": { + "type": "boolean" + } + } + } + } + } + }, + "400": { + "description": "Request error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/error" + }, + "examples": { + "1": { + "$ref": "#/components/examples/ErrorNoToken" + }, + "2": { + "$ref": "#/components/examples/ErrorTokenNotExist" + }, + "3": { + "$ref": "#/components/examples/ErrorInvalidToken" + }, + "4": { + "$ref": "#/components/examples/ErrorThrottling" + }, + "5": { + "$ref": "#/components/examples/ErrorNoClientSecret" + }, + "6": { + "$ref": "#/components/examples/ErrorInvalidClientSecret" + }, + "7": { + "$ref": "#/components/examples/ErrorInactiveToken" + }, + "No module IDs provided": { + "value": { + "ok": false, + "error": "No module IDs provided." + } + }, + "Invalid module IDs provided": { + "value": { + "ok": false, + "error": "One or mote invalid Module IDs supplied." + } + } + } + } + } + } + } + } + }, + "/timetable/data/departments": { + "get": { + "summary": "Returns a list of every department at UCL, along with its internal name.", + "description": "This can be used with the /data/modules endpoint to request information on all modules for a department.", + "tags": [ + "Timetable" + ], + "security": [ + { + "OAuthSecurity": [], + "OAuthToken": [] + } + ], + "responses": { + "200": { + "description": "A list of department objects.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "ok": { + "type": "boolean" + }, + "departments": { + "type": "array", + "items": { + "$ref": "#/components/schemas/department" + } + } + } + } + } + } + }, + "400": { + "description": "Request error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/error" + }, + "examples": { + "1": { + "$ref": "#/components/examples/ErrorNoToken" + }, + "2": { + "$ref": "#/components/examples/ErrorTokenNotExist" + }, + "3": { + "$ref": "#/components/examples/ErrorInvalidToken" + }, + "4": { + "$ref": "#/components/examples/ErrorThrottling" + }, + "5": { + "$ref": "#/components/examples/ErrorNoClientSecret" + }, + "6": { + "$ref": "#/components/examples/ErrorInvalidClientSecret" + }, + "7": { + "$ref": "#/components/examples/ErrorInactiveToken" + } + } + } + } + } + } + } + }, + "/timetable/data/modules": { + "get": { + "summary": "Returns a list of every module taught by a given department at UCL.", + "tags": [ + "Timetable" + ], + "security": [ + { + "OAuthSecurity": [], + "OAuthToken": [] + } + ], + "parameters": [ + { + "name": "department", + "in": "query", + "description": "The department ID available from /data/departments.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "A list of department objects.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "ok": { + "type": "boolean" + }, + "modules": { + "type": "object", + "additionalProperties": { + "$ref": "#/components/schemas/module_data_courses_modules" + } + } + } + } + } + } + }, + "400": { + "description": "Request error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/error" + }, + "examples": { + "1": { + "$ref": "#/components/examples/ErrorNoToken" + }, + "2": { + "$ref": "#/components/examples/ErrorTokenNotExist" + }, + "3": { + "$ref": "#/components/examples/ErrorInvalidToken" + }, + "4": { + "$ref": "#/components/examples/ErrorThrottling" + }, + "5": { + "$ref": "#/components/examples/ErrorNoClientSecret" + }, + "6": { + "$ref": "#/components/examples/ErrorInvalidClientSecret" + }, + "7": { + "$ref": "#/components/examples/ErrorInactiveToken" + } + } + } + } + } + } + } + }, + "/timetable/data/courses": { + "get": { + "summary": "Returns a list of every course taught by a given department at UCL.", + "tags": [ + "Timetable" + ], + "security": [ + { + "OAuthSecurity": [], + "OAuthToken": [] + } + ], + "parameters": [ + { + "name": "department", + "in": "query", + "description": "The department ID available from /data/departments.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "A list of department objects.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "ok": { + "type": "boolean" + }, + "courses": { + "type": "array", + "items": { + "$ref": "#/components/schemas/course" + } + } + } + } + } + } + }, + "400": { + "description": "Request error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/error" + }, + "examples": { + "1": { + "$ref": "#/components/examples/ErrorNoToken" + }, + "2": { + "$ref": "#/components/examples/ErrorTokenNotExist" + }, + "3": { + "$ref": "#/components/examples/ErrorInvalidToken" + }, + "4": { + "$ref": "#/components/examples/ErrorThrottling" + }, + "5": { + "$ref": "#/components/examples/ErrorNoClientSecret" + }, + "6": { + "$ref": "#/components/examples/ErrorInvalidClientSecret" + }, + "7": { + "$ref": "#/components/examples/ErrorInactiveToken" + }, + "No department ID provided": { + "value": { + "ok": false, + "error": "No department ID provided." + } + } + } + } + } + } + } + } + }, + "/timetable/data/courses/modules": { + "get": { + "summary": "Returns a list of every module taught on a given course at UCL.", + "tags": [ + "Timetable" + ], + "security": [ + { + "OAuthSecurity": [], + "OAuthToken": [] + } + ], + "parameters": [ + { + "name": "course", + "in": "query", + "description": "The course ID available from /data/courses.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "term_1", + "in": "query", + "description": "Boolean designating if you would like module instances that are taught in term 1.", + "required": false, + "schema": { + "type": "boolean" + } + }, + { + "name": "term_2", + "in": "query", + "description": "Boolean designating if you would like module instances that are taught in term 2.", + "required": false, + "schema": { + "type": "boolean" + } + }, + { + "name": "term_3", + "in": "query", + "description": "Boolean designating whether or not you want module instances that are taught in term 3.", + "required": false, + "schema": { + "type": "boolean" + } + }, + { + "name": "term_1_next_year", + "in": "query", + "description": "Boolean designating if you would like module instances that are taught in term 1 of the next academic year. This is used by admissions to calculate the end dates for non-standard programmes, and therefore is rare", + "required": false, + "schema": { + "type": "boolean" + } + }, + { + "name": "summer", + "in": "query", + "description": "Boolean designating if you would like module instances that are timetabled in the summer. This can happen in some Postgraduate and Medicine teaching arrangements, but is rare. Note that this is NOT the same as the UCL Summer School.", + "required": false, + "schema": { + "type": "boolean" + } + }, + { + "name": "year_long", + "in": "query", + "description": "Boolean designating if you would like module instances where the course is timetabled to last for an entire academic year.", + "required": false, + "schema": { + "type": "boolean" + } + }, + { + "name": "lsr", + "in": "query", + "description": "Boolean designating if you would like module instances where the module is timetabled during the Late Summer Resit period. This is used internally by Examinations to timetable Late Summer Assessments (LSAs).", + "required": false, + "schema": { + "type": "boolean" + } + }, + { + "name": "is_summer_school", + "in": "query", + "description": "Boolean designating if you would like module instances where the course is taught as part of the UCL Summer School (true) or standard academic teaching (false).", + "required": false, + "schema": { + "type": "boolean" + } + }, + { + "name": "session_1", + "in": "query", + "description": "Boolean designating if you would like module instances where the module is taught in the first summer school session of this academic year's summer.", + "required": false, + "schema": { + "type": "boolean" + } + }, + { + "name": "session_2", + "in": "query", + "description": "Boolean designating if you would like module instances where the module is taught in the second summer school session of this academic year's summer.", + "required": false, + "schema": { + "type": "boolean" + } + }, + { + "name": "is_undergraduate", + "in": "query", + "description": "Boolean designating if you would like undergraduate module instances.", + "required": false, + "schema": { + "type": "boolean" + } + }, + { + "name": "only_available", + "in": "query", + "description": "Boolean designating if you would only like available module instances (i.e. ones that are not compulsory for the course).", + "required": false, + "schema": { + "type": "boolean" + } + }, + { + "name": "only_compulsory", + "in": "query", + "description": "Boolean designating if you would only like compulsory module instances.", + "required": false, + "schema": { + "type": "boolean" + } + } + ], + "responses": { + "200": { + "description": "A list of department objects.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "ok": { + "type": "boolean" + }, + "modules": { + "type": "object", + "additionalProperties": { + "$ref": "#/components/schemas/module_data_courses_modules" + } + } + } + } + } + } + }, + "400": { + "description": "Request error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/error" + }, + "examples": { + "1": { + "$ref": "#/components/examples/ErrorNoToken" + }, + "2": { + "$ref": "#/components/examples/ErrorTokenNotExist" + }, + "3": { + "$ref": "#/components/examples/ErrorInvalidToken" + }, + "4": { + "$ref": "#/components/examples/ErrorThrottling" + }, + "5": { + "$ref": "#/components/examples/ErrorNoClientSecret" + }, + "6": { + "$ref": "#/components/examples/ErrorInvalidClientSecret" + }, + "7": { + "$ref": "#/components/examples/ErrorInactiveToken" + }, + "No course ID provided": { + "value": { + "ok": false, + "error": "No course ID provided." + } + }, + "Invalid paramenter type": { + "value": { + "ok": false, + "error": "Given parameter is not of correct type" + } + }, + "Invalid parameters": { + "value": { + "ok": false, + "error": "only_available and only_compulsory cannot both be true" + } + } + } + } + } + } + } + } + }, + "/oauth/authorise": { + "get": { + "summary": "Authorises a user against the API", + "description": "This endpoint should be used to authorise a user against the API.\n\nIt will perform a redirect if the user successfully logged in and accepted/denied the request.\n\nSee the below code samples for how you might implement this in your code.\n\nPython:\n```python\n url = \"https://uclapi.com/oauth/authorise/?client_id=123&state=1\"\n\n'''\n in a desktop app, script, or for testing\n'''\nimport webbrowser\nwebbrowser.open_new(url) \n# note that you will also need some way receive the callback\n# this can be done via a web server (e.g. below)\n\n'''\n on a Flask server\n this example covers both redirecting the user to\n the /authorise page and receiving the callback\n'''\nfrom flask import Flask, redirect, request\napp = Flask(__name__)\n\n@app.route('/login')\ndef uclapi_login():\n return redirect(url)\n\n@app.route('/callback')\ndef receive_callback():\n # receive parameters\n result = request.args.get('result', '')\n code = request.args.get('code', '')\n state = request.args.get('state', '')\n # do something with these parameters\n # e.g. request an auth token from /oauth/token\n return\n```\n\nShell:\n```shell\n # linux\n xdg-open \"https://uclapi.com/oauth/authorise/?client_id=123.456&state=1\"\n \n # WSL\n cmd.exe /c start \"https://uclapi.com/oauth/authorise/?client_id=123^&state=1\"\n\n # note that you will also need some way to receive the callback\n```\n\nJavaScript:\n```js\nconst url = \"https://uclapi.com/oauth/authorise/?client_id=123.456&state=1\"\n\n/* in-browser */\nwindow.location.href = url\n// note that you will also need some way to receive the callback\n// this can be done via a web server (e.g. below)\n\n/* Node.JS Express server */\nconst express = require('express')\nconst app = express()\n\napp.get('/login', (req, res) => res.redirect(url))\napp.get('/callback', (req, res) => {\n const {\n result,\n code,\n state\n } = req.params\n // do something with these parameters\n // e.g. request an auth token from /oauth/token\n})\n\napp.listen(3000)\n```", + "tags": [ + "OAuth" + ], + "parameters": [ + { + "name": "client_id", + "in": "query", + "description": "Client ID of the authenticating app.", + "required": true, + "schema": { + "type": "string", + "example": "9020633324528794.9923205739531139" + } + }, + { + "name": "state", + "in": "query", + "description": "OAuth (random) state.", + "required": true, + "schema": { + "type": "string", + "example": "jAifrW3" + } + } + ], + "responses": { + "302": { + "description": "Redirection. See the expected query parameters in the URL description below.", + "headers": { + "Location": { + "description": "The redirection performed on success OR failure.\nThe URL will have the following query parameters:\n- `client_id` - the Client ID of the authentication app (e.g. `123456`)\n- `state` - the same state parameter originally sent as a query parameter to /oauth/authorise (e.g. `jAifrW3`)\n- `result` - either `allowed` or `denied` depending on whether the user granted permission\n- `code` - a secret code to be used to obtain an OAuth token via the /oauth/token endpoint (e.g. `mysecretcode`)", + "schema": { + "type": "string", + "format": "uri" + } + } + } + }, + "400": { + "description": "OAuth error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/error" + }, + "examples": { + "Incorrect parameters supplied": { + "value": { + "ok": false, + "error": "You did not supply a client_id and a state in your request." + } + }, + "App does not exist for client id": { + "value": { + "ok": false, + "error": "You supplied an invalid client_id." + } + }, + "No callback URL set for this app": { + "value": { + "ok": false, + "error": "You did not set a callback URL for your app." + } + }, + "UCL has sent incomplete headers": { + "value": { + "ok": false, + "error": "UCL sent us incomplete headers. If the issue persists, please contact the UCL API Team." + } + } + } + } + } + } + } + } + }, + "/oauth/token": { + "get": { + "summary": "A token will be generated which your app can use to get user’s personal data in JSON format from the OAuthSecurity/user/data.", + "description": "This endpoint should be used to obtain a token for use in the other API endpoints.\n\nSee the below code samples for how you might implement this in your code.\n\nPython:\n```python\nimport requests\n\nparams = {\n \"client_id\": \"123.456\",\n \"code\": \"1\",\n \"client_secret\": \"secret\",\n}\nr = requests.get(\"https://uclapi.com/oauth/token\", params=params)\nprint(r.json())\n```\n\nShell:\n```shell\ncurl -G https://uclapi.com/oauth/token -d code=mysecretcode -d client_id=123.456 -d client_secret=secret\n```\n\nJavaScript:\n```js\nfetch(\"https://uclapi.com/oauth/token?code=mysecretcode&client_id=123.456&client_secret=secret\")\n .then(response => response.json())\n .then(json => console.log(json));\n```", + "tags": [ + "OAuth" + ], + "security": [ + { + "OAuthSecurity": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/client_secret" + }, + { + "name": "client_id", + "in": "query", + "description": "Client ID of the authenticating app.", + "required": true, + "schema": { + "type": "string", + "example": "9020633324528794.9923205739531139" + } + }, + { + "name": "code", + "in": "query", + "description": "Secret code obtained from the authorise endpoint.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "ok": { + "type": "boolean" + }, + "state": { + "type": "string" + }, + "scope": { + "type": "array", + "items": { + "type": "string" + } + }, + "client_id": { + "type": "string" + }, + "token": { + "type": "string" + } + } + } + } + } + }, + "400": { + "description": "OAuth error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/error" + }, + "examples": { + "Incomplete data": { + "value": { + "ok": false, + "error": "The client did not provide the requisite data to get a token." + } + }, + "Invalid/Expired code": { + "value": { + "ok": false, + "error": "The code received was invalid, or has expired. Please try again." + } + }, + "Non-existent client": { + "value": { + "ok": false, + "error": "App has been deleted or the Client ID is invalid." + } + }, + "Invalid client secret": { + "value": { + "ok": false, + "error": "Client secret incorrect" + } + } + } + } + } + } + } + } + }, + "/oauth/user/data": { + "get": { + "summary": "Returns personal data on a student at UCL.", + "tags": [ + "OAuth" + ], + "security": [ + { + "OAuthSecurity": [], + "OAuthToken": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/client_secret" + } + ], + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/user_data" + } + } + } + }, + "400": { + "description": "OAuth error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/error" + }, + "examples": { + "1": { + "$ref": "#/components/examples/ErrorNoToken" + }, + "2": { + "$ref": "#/components/examples/ErrorInvalidClientSecret" + }, + "3": { + "$ref": "#/components/examples/ErrorInvalidToken" + }, + "4": { + "$ref": "#/components/examples/ErrorThrottling" + }, + "5": { + "$ref": "#/components/examples/ErrorNoClientSecret" + }, + "6": { + "$ref": "#/components/examples/ErrorInvalidClientSecret" + }, + "7": { + "$ref": "#/components/examples/ErrorInactiveToken" + }, + "8": { + "$ref": "#/components/examples/ErrorPersonalData" + } + } + } + } + } + } + } + }, + "/oauth/user/studentnumber": { + "get": { + "summary": "You can use the oauth/user/data endpoint to find out whether the user is a student before you call this endpoint. If you call this endpoint and the user is not a student, an error will be returned.", + "description": "Please note: to use this endpoint you must have ticked the Student Number scope for your application in the Dashboard. This piece of information has been separated from the others because a student number can in some cases be considered confidential. This is because any data exported directly from Portico, SITS (E:Vision) or CMIS is usually grouped by Student Number. One example is that in some cases departments choose to release spreadsheets of examination results where each student is identified by their student number, and not their name, to provide a degree of anonymity in what is otherwise an open data set. You should consider carefully whether you actually need a student number to track students when other unique identifiers are available, such as their username-based email address and UPI. If you request a student number and it is not required for your application, your users may choose not to provide this information to you, and therefore deny your application permission to access their details.", + "tags": [ + "OAuth" + ], + "security": [ + { + "OAuthSecurity": [ + "student_number" + ], + "OAuthToken": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/client_secret" + } + ], + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "ok": { + "type": "boolean" + }, + "student_number": { + "type": "string" + } + } + } + } + } + }, + "400": { + "description": "OAuth error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/error" + }, + "examples": { + "1": { + "$ref": "#/components/examples/ErrorNoToken" + }, + "2": { + "$ref": "#/components/examples/ErrorInvalidClientSecret" + }, + "3": { + "$ref": "#/components/examples/ErrorInvalidToken" + }, + "4": { + "$ref": "#/components/examples/ErrorThrottling" + }, + "5": { + "$ref": "#/components/examples/ErrorNoClientSecret" + }, + "6": { + "$ref": "#/components/examples/ErrorInvalidClientSecret" + }, + "7": { + "$ref": "#/components/examples/ErrorInactiveToken" + }, + "8": { + "$ref": "#/components/examples/ErrorRejectedScope" + }, + "User is not a student": { + "value": { + "ok": false, + "error": "User is not a student." + } + } + } + } + } + } + } + } + }, + "/roombookings/rooms": { + "get": { + "summary": "Returns rooms and information about them.", + "description": "If you don’t specify any query parameters besides the token, all rooms will be returned.\n\nNote: This endpoint only returns publicly bookable rooms. Departmentally bookable rooms are not included. In the response, the room field contains a list of rooms that match your query. If no filters are applied, all rooms will be returned.", + "tags": [ + "Room Bookings" + ], + "security": [ + { + "OAuthSecurity": [], + "OAuthToken": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/roomname" + }, + { + "$ref": "#/components/parameters/roomid" + }, + { + "$ref": "#/components/parameters/siteid" + }, + { + "$ref": "#/components/parameters/sitename" + }, + { + "$ref": "#/components/parameters/classification" + }, + { + "$ref": "#/components/parameters/capacity" + } + ], + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "ok": { + "type": "boolean" + }, + "rooms": { + "type": "array", + "items": { + "$ref": "#/components/schemas/room" + } + } + } + } + } + } + }, + "400": { + "description": "Request error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/error" + }, + "examples": { + "1": { + "$ref": "#/components/examples/ErrorNoToken" + }, + "2": { + "$ref": "#/components/examples/ErrorTokenNotExist" + }, + "3": { + "$ref": "#/components/examples/ErrorInvalidToken" + }, + "4": { + "$ref": "#/components/examples/ErrorThrottling" + }, + "5": { + "$ref": "#/components/examples/ErrorNoClientSecret" + }, + "6": { + "$ref": "#/components/examples/ErrorInvalidClientSecret" + }, + "7": { + "$ref": "#/components/examples/ErrorInactiveToken" + }, + "Invalid capacity": { + "value": { + "ok": false, + "error": "capacity should always be an int" + } + } + } + } + } + } + } + } + }, + "/roombookings/bookings": { + "get": { + "summary": "Returns the results to a bookings or space availability query. It returns a paginated list of bookings.", + "description": "Note: This endpoint only returns publicly bookable rooms. Departmentally bookable rooms are not included.", + "tags": [ + "Room Bookings" + ], + "security": [ + { + "OAuthSecurity": [], + "OAuthToken": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/roomname" + }, + { + "$ref": "#/components/parameters/roomid" + }, + { + "$ref": "#/components/parameters/start_datetime" + }, + { + "$ref": "#/components/parameters/end_datetime" + }, + { + "$ref": "#/components/parameters/date" + }, + { + "$ref": "#/components/parameters/siteid" + }, + { + "$ref": "#/components/parameters/description" + }, + { + "$ref": "#/components/parameters/contact" + }, + { + "$ref": "#/components/parameters/results_per_page" + } + ], + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "ok": { + "type": "boolean" + }, + "next_page_exists": { + "type": "boolean" + }, + "page_token": { + "type": "string" + }, + "count": { + "type": "number" + }, + "bookings": { + "type": "array", + "items": { + "$ref": "#/components/schemas/booking" + } + } + } + } + } + } + }, + "400": { + "description": "Request error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/error" + }, + "examples": { + "1": { + "$ref": "#/components/examples/ErrorNoToken" + }, + "2": { + "$ref": "#/components/examples/ErrorTokenNotExist" + }, + "3": { + "$ref": "#/components/examples/ErrorInvalidToken" + }, + "4": { + "$ref": "#/components/examples/ErrorThrottling" + }, + "5": { + "$ref": "#/components/examples/ErrorNoClientSecret" + }, + "6": { + "$ref": "#/components/examples/ErrorInvalidClientSecret" + }, + "7": { + "$ref": "#/components/examples/ErrorInactiveToken" + }, + "Invalid date/time": { + "value": { + "ok": false, + "error": "start_datetime/end_datetime isn't formatted as suggested in the docs" + } + }, + "Invalid results_per_page": { + "value": { + "ok": false, + "error": "results_per_page should be an integer" + } + }, + "Non-existent page token": { + "value": { + "ok": false, + "error": "Page token does not exist" + } + } + } + } + } + } + } + } + }, + "/roombookings/equipment": { + "get": { + "summary": "Returns any equipment/feature information about a specific room.", + "description": "So, for example whether there is a Whiteboard or a DVD Player in the room. A full example can be seen here.", + "tags": [ + "Room Bookings" + ], + "security": [ + { + "OAuthSecurity": [], + "OAuthToken": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/roomid" + }, + { + "$ref": "#/components/parameters/siteid" + } + ], + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "ok": { + "type": "boolean" + }, + "equipment": { + "type": "array", + "items": { + "$ref": "#/components/schemas/equipment" + } + } + } + } + } + } + }, + "400": { + "description": "Request error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/error" + }, + "examples": { + "1": { + "$ref": "#/components/examples/ErrorNoToken" + }, + "2": { + "$ref": "#/components/examples/ErrorTokenNotExist" + }, + "3": { + "$ref": "#/components/examples/ErrorInvalidToken" + }, + "4": { + "$ref": "#/components/examples/ErrorThrottling" + }, + "5": { + "$ref": "#/components/examples/ErrorNoClientSecret" + }, + "6": { + "$ref": "#/components/examples/ErrorInvalidClientSecret" + }, + "7": { + "$ref": "#/components/examples/ErrorInactiveToken" + }, + "Invalid roomid": { + "value": { + "ok": false, + "error": "No roomid supplied" + } + }, + "Invalid siteid": { + "value": { + "ok": false, + "error": "No siteid supplied" + } + } + } + } } } } } - } - }, - "paths": { - "/timetable/personal": { + }, + "/roombookings/freerooms": { "get": { - "summary": "Returns the personal timetable of the user.", + "summary": "Given a start time and an end time, this endpoint returns all rooms which are free in that time range.", + "description": "Note: This endpoint only returns publicly bookable rooms. Departmentally bookable rooms are not included.", "tags": [ - "Timetable" + "Room Bookings" ], "security": [ { - "OAuthSecurity": [ - "personal_timetable" - ], + "OAuthSecurity": [], "OAuthToken": [] } ], "parameters": [ { - "$ref": "#/components/parameters/client_secret" + "$ref": "#/components/parameters/start_datetime" }, { - "name": "date", - "in": "query", - "description": "A date to filter entries by", - "required": false, - "schema": { - "type": "string" - } + "$ref": "#/components/parameters/end_datetime" } ], "responses": { "200": { - "description": "A timetable.", + "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { - "timetable": { - "$ref": "#/components/schemas/timetable" - }, "ok": { "type": "boolean" + }, + "count": { + "type": "integer" + }, + "free_rooms": { + "type": "array", + "items": { + "$ref": "#/components/schemas/room" + } } } } @@ -1628,11 +3576,17 @@ "7": { "$ref": "#/components/examples/ErrorInactiveToken" }, - "8": { - "$ref": "#/components/examples/ErrorPersonalData" + "Invalid parameters": { + "value": { + "ok": false, + "error": "start_datetime or end_datetime not provided" + } }, - "9": { - "$ref": "#/components/examples/ErrorRejectedScope" + "Invalid date/time": { + "value": { + "ok": false, + "error": "start_datetime/end_datetime isn't formatted as suggested in the docs" + } } } } @@ -1641,11 +3595,12 @@ } } }, - "/timetable/bymodule": { + "/search/people": { "get": { - "summary": "Returns a yearly timetable for the supplied modules.", + "summary": "Returns matching people and information about them.", + "description": "Note that this endpoint only returns a maximum of 20 matches.\n\nFollowing a change to UCL's systems in 2019, this endpoint only returns staff; students will not be returned through this API.", "tags": [ - "Timetable" + "Search" ], "security": [ { @@ -1655,37 +3610,107 @@ ], "parameters": [ { - "name": "modules", + "name": "query", "in": "query", - "description": "A comma-separated list of the module codes you want the timetable of. You can supply either standard module codes (e.g. COMP0133), or full codes including the instance of the module (COMP0133-A7U-T1). Note that if you do not supply an instance, every single timetable entry will be returned including duplicates for the same module taught as multiple instances. It is recommended that a full module code including instance be supplied.", + "description": "Name of the person you are searching for.", "required": true, "schema": { "type": "string" } + } + ], + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "ok": { + "type": "boolean" + }, + "people": { + "type": "array", + "items": { + "$ref": "#/components/schemas/person" + } + } + } + } + } + } }, - { - "name": "date", - "in": "query", - "description": "A date to filter entries by", - "required": false, - "schema": { - "type": "string" + "400": { + "description": "Request error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/error" + }, + "examples": { + "1": { + "$ref": "#/components/examples/ErrorNoToken" + }, + "2": { + "$ref": "#/components/examples/ErrorTokenNotExist" + }, + "3": { + "$ref": "#/components/examples/ErrorInvalidToken" + }, + "4": { + "$ref": "#/components/examples/ErrorThrottling" + }, + "5": { + "$ref": "#/components/examples/ErrorNoClientSecret" + }, + "6": { + "$ref": "#/components/examples/ErrorInvalidClientSecret" + }, + "7": { + "$ref": "#/components/examples/ErrorInactiveToken" + }, + "Invalid query": { + "value": { + "ok": false, + "error": "No query provided" + } + } + } + } } } + } + } + }, + "/resources/desktops": { + "get": { + "summary": "Returns number of desktops and how many are free at the time of making the request.", + "tags": [ + "Resources" + ], + "security": [ + { + "OAuthSecurity": [], + "OAuthToken": [] + } ], "responses": { "200": { - "description": "A timetable.", + "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { - "timetable": { - "$ref": "#/components/schemas/timetable" - }, "ok": { "type": "boolean" + }, + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/desktop_data" + } } } } @@ -1721,16 +3746,16 @@ "7": { "$ref": "#/components/examples/ErrorInactiveToken" }, - "No module IDs provided": { + "Error retrieving data": { "value": { "ok": false, - "error": "No module IDs provided." + "error": "Could not retrieve availability data. Please try again later or contact us for support." } }, - "Invalid module IDs provided": { + "Error parsing data": { "value": { "ok": false, - "error": "One or mote invalid Module IDs supplied." + "error": "Could not parse the desktop availability data. Please try again later or contact us for support." } } } @@ -1740,12 +3765,94 @@ } } }, - "/timetable/data/departments": { + "/workspaces/surveys": { "get": { - "summary": "Returns a list of every department at UCL, along with its internal name.", - "description": "This can be used with the /data/modules endpoint to request information on all modules for a department.", + "summary": "Returns all UCL libraries with the Cad-Capture devices fitted to the seats", + "description": "Each library is known as a 'survey', as it is a survey of the building. Within each survey there are multiple 'maps', each of which corresponds to a section such as a level, wing or separated library work area. Each sensor is tied to a specific map, and each map belongs to a survey.\n\nThe surveys key contains a list of dictionaries, each of which corresponds to a library survey with seating sensors attached. Each survey has a number of maps, corresponding to regions within the library, such as a different floor or wing. Note that the location[address] field will not always contain a precise address, and may simply contain the address to the UCL campus (i.e. Gower Street, London), which may not be helpful. If it is present, the location[coordinates] will generally be more precise.", + "tags": [ + "Workspaces" + ], + "security": [ + { + "OAuthSecurity": [], + "OAuthToken": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/survey_filter" + } + ], + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "ok": { + "type": "boolean" + }, + "surveys": { + "type": "array", + "items": { + "$ref": "#/components/schemas/survey" + } + } + } + } + } + } + }, + "400": { + "description": "Request error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/error" + }, + "examples": { + "1": { + "$ref": "#/components/examples/ErrorNoToken" + }, + "2": { + "$ref": "#/components/examples/ErrorTokenNotExist" + }, + "3": { + "$ref": "#/components/examples/ErrorInvalidToken" + }, + "4": { + "$ref": "#/components/examples/ErrorThrottling" + }, + "5": { + "$ref": "#/components/examples/ErrorNoClientSecret" + }, + "6": { + "$ref": "#/components/examples/ErrorInvalidClientSecret" + }, + "7": { + "$ref": "#/components/examples/ErrorInactiveToken" + }, + "Invalid filter": { + "value": { + "ok": false, + "error": "The survey filter you provided is invalid. Valid survey filters are: all,staff,student" + } + } + } + } + } + } + } + } + }, + "/workspaces/sensors": { + "get": { + "summary": "Provides a list of every sensor within every map in a survey/library.", + "description": "It can optionally provide the current state of a sensor (e.g. Occupied / Absent), but by default it will only list the sensors without their states.\n\nThis endpoint will return a list of every map within a survey, and within it every sensor associated with that map. It will optionally also return the latest triggered state of that sensor (e.g. whether the seat was marked triggered or occupied).\n\nNote that the following response data table is deliberately incomplete. This is because we return additional metadata that is not yet useful, and often left blank by the provider. We will update this documentation if and when these extra parameters become useful.", "tags": [ - "Timetable" + "Workspaces" ], "security": [ { @@ -1753,9 +3860,23 @@ "OAuthToken": [] } ], + "parameters": [ + { + "$ref": "#/components/parameters/survey_id" + }, + { + "name": "return_states", + "in": "query", + "description": "Whether or not to return the latest trigger state of each sensor. Defaults to false. For live data, set this to true.", + "required": false, + "schema": { + "type": "boolean" + } + } + ], "responses": { "200": { - "description": "A list of department objects.", + "description": "Success", "content": { "application/json": { "schema": { @@ -1764,10 +3885,16 @@ "ok": { "type": "boolean" }, - "departments": { + "survey_name": { + "type": "string" + }, + "survey_id": { + "type": "number" + }, + "maps": { "type": "array", "items": { - "$ref": "#/components/schemas/department" + "$ref": "#/components/schemas/map_with_sensors" } } } @@ -1803,6 +3930,18 @@ }, "7": { "$ref": "#/components/examples/ErrorInactiveToken" + }, + "Missing parameter": { + "value": { + "ok": false, + "error": "Please specify a survey_id." + } + }, + "Invalid parameter": { + "value": { + "ok": false, + "error": "The survey_id you specified was not valid." + } } } } @@ -1811,11 +3950,12 @@ } } }, - "/timetable/data/modules": { + "/workspaces/sensors/averages/time": { "get": { - "summary": "Returns a list of every module taught by a given department at UCL.", + "summary": "Provides a list of every sensor within every map in a survey/library.", + "description": " It can optionally provide the current state of a sensor (e.g. Occupied / Absent), but by default it will only list the sensors without their states.\n\nThis endpoint will show for every survey_id provided the average utilisation of the associated library at ten minute intervals throughout the day. This can be used, for example, in apps and integrations which show users how busy each library is at given times of the day. You can show data based on the last day (e.g. yesterday), the last week or the last month. Each day's data is updated in the early hours of the morning (around 2am) so that users during the day have the latest data.\n\nThis endpoint will return a list with every survey requested, its ID, its name and average data for the period requested for every 10 minute period in a day. The averages are not ordered, so it is recommended that the data is fed into some other code to transform the data in such as way as to ensure that it is user-friendly. One example might be a graphing library to plot the data throughout the day to produce an average occupancy graph.\n\nPlease note that the counts below may not perfectly add up. This is because we perform an integer division calculation to get an average based on multiple days' worth of data, so you may encounter off-by-one errors if you check that sensors_absent + sensors_occupied == sensors_total. Please do not be alarmed by this! However, if you do get large, unexplained differences do let us know so that we can look into it.\n\nPlease note further that there are some rare situations where the data source we use may have historical data missing. Sitautions that can cause this include new libraries being added which do not yet have historical data available, and situations where data has not properly been saved by our data provider. In cases like this, our response to your app will include an empty averages object with no times within it. Your code should account for this possibility by checking whether each time period is actually present. If time periods are missing your application should alert the user to data being missing and fail gracefully.", "tags": [ - "Timetable" + "Workspaces" ], "security": [ { @@ -1825,18 +3965,24 @@ ], "parameters": [ { - "name": "department", + "name": "days", "in": "query", - "description": "The department ID available from /data/departments.", + "description": "An integer number of days (either 1, 7 or 30) from which to deliver average data. The format of the data returned does not change based on this value, but the actual averaged figures do. When days is 1, the API will return the data from the previous complete day; when days is 7 the API will return data from the last week and when it is set to 30 the API will return data from the last 30 days, which is approx. one month.", "required": true, "schema": { "type": "string" } + }, + { + "$ref": "#/components/parameters/survey_ids" + }, + { + "$ref": "#/components/parameters/survey_filter" } ], "responses": { "200": { - "description": "A list of department objects.", + "description": "Success", "content": { "application/json": { "schema": { @@ -1845,10 +3991,10 @@ "ok": { "type": "boolean" }, - "modules": { - "type": "object", - "additionalProperties": { - "$ref": "#/components/schemas/module_data_courses_modules" + "surveys": { + "type": "array", + "items": { + "$ref": "#/components/schemas/sensor_average_survey" } } } @@ -1884,6 +4030,36 @@ }, "7": { "$ref": "#/components/examples/ErrorInactiveToken" + }, + "Invalid filter": { + "value": { + "ok": false, + "error": "The survey filter you provided is invalid. Valid survey filters are: all,staff,student" + } + }, + "Missing days parameter": { + "value": { + "ok": false, + "error": "You did not specify how many days of historical data should be returned. Valid options are: 1,7,30" + } + }, + "Invalid days parameter": { + "value": { + "ok": false, + "error": "You did not specify an integer number of days of historical days, Valid options are: 1,7,30" + } + }, + "Unsupported days parameter": { + "value": { + "ok": false, + "error": "You did not specify a valid number of days of historical days, Valid options are: 1,7,30" + } + }, + "Invalid survey IDs": { + "value": { + "ok": false, + "error": "One or more of the survey_ids you requested is not valid." + } } } } @@ -1892,11 +4068,12 @@ } } }, - "/timetable/data/courses": { + "/workspaces/sensors/lastupdated": { "get": { - "summary": "Returns a list of every course taught by a given department at UCL.", + "summary": "Replies with the timestamp of the last time the sensor data was updated for a given survey.", + "description": "This allows integrations that poll the API to save on request time by only requesting the full set of sensor information for a survey once it has been updated.", "tags": [ - "Timetable" + "Workspaces" ], "security": [ { @@ -1906,18 +4083,12 @@ ], "parameters": [ { - "name": "department", - "in": "query", - "description": "The department ID available from /data/departments.", - "required": true, - "schema": { - "type": "string" - } + "$ref": "#/components/parameters/survey_id" } ], "responses": { "200": { - "description": "A list of department objects.", + "description": "Success", "content": { "application/json": { "schema": { @@ -1926,11 +4097,13 @@ "ok": { "type": "boolean" }, - "courses": { - "type": "array", - "items": { - "$ref": "#/components/schemas/course" - } + "last_updated": { + "type": "string", + "example": "2018-02-16T15:33:01" + }, + "survey_id": { + "type": "number", + "example": "46" } } } @@ -1966,10 +4139,16 @@ "7": { "$ref": "#/components/examples/ErrorInactiveToken" }, - "No department ID provided": { + "Missing survey ID": { "value": { "ok": false, - "error": "No department ID provided." + "error": "Please specify a survey_id" + } + }, + "Invalid survey ID": { + "value": { + "ok": false, + "error": "The survey_id you specified is not valid." } } } @@ -1979,11 +4158,20 @@ } } }, - "/timetable/data/courses/modules": { + "/workspaces/sensors/summary": { "get": { - "summary": "Returns a list of every module taught on a given course at UCL.", + "summary": "Summarises, with a one-minute accuracy, the number of seats within each library region that are free and occupied.", + "description": "It is best suited to integrations which show cumulative, live data. Developers can use this endpoint to avoid making many parallel or sequential requests to fetch survey sensor counts.\n\nThis endpoint takes into account UCL's thirty minute rule, which allows students to leave their seat unattended for up to thirty minutes at a time (e.g. to use the bathroom or get food). This means that the Summary endpoint may return a lower number of available seats when compared to reality if many students leave the library within a short period of time. The UCL Library's website and the UCL Go! mobile application both follow this rule, so your app or integration should have parity with first party data sources by using the UCL API.\n\nThis endpoint will return a list with every survey requested, and its associated maps. Within each map is a count of absent (i.e. vacant) and occupied seats. The endpoint also returns the total number of seats in each library that are absent or occupied.\n\nIf your application or integration is designed to inform students of the total number of free seats in a library please ensure you use the survey total figures. This is because many sensors have not yet been assigned to maps on our data provider's system which means that relying only on map counts will leave many seats unaccounted for. We are actively working with our data provider to rectify this, and we apologise for any inconvenience caused.", "tags": [ - "Timetable" + "Workspaces" + ], + "parameters": [ + { + "$ref": "#/components/parameters/survey_ids" + }, + { + "$ref": "#/components/parameters/survey_filter" + } ], "security": [ { @@ -1991,137 +4179,112 @@ "OAuthToken": [] } ], - "parameters": [ - { - "name": "course", - "in": "query", - "description": "The course ID available from /data/courses.", - "required": true, - "schema": { - "type": "string" - } - }, - { - "name": "term_1", - "in": "query", - "description": "Boolean designating if you would like module instances that are taught in term 1.", - "required": false, - "schema": { - "type": "boolean" - } - }, - { - "name": "term_2", - "in": "query", - "description": "Boolean designating if you would like module instances that are taught in term 2.", - "required": false, - "schema": { - "type": "boolean" - } - }, - { - "name": "term_3", - "in": "query", - "description": "Boolean designating whether or not you want module instances that are taught in term 3.", - "required": false, - "schema": { - "type": "boolean" - } - }, - { - "name": "term_1_next_year", - "in": "query", - "description": "Boolean designating if you would like module instances that are taught in term 1 of the next academic year. This is used by admissions to calculate the end dates for non-standard programmes, and therefore is rare", - "required": false, - "schema": { - "type": "boolean" - } - }, - { - "name": "summer", - "in": "query", - "description": "Boolean designating if you would like module instances that are timetabled in the summer. This can happen in some Postgraduate and Medicine teaching arrangements, but is rare. Note that this is NOT the same as the UCL Summer School.", - "required": false, - "schema": { - "type": "boolean" - } - }, - { - "name": "year_long", - "in": "query", - "description": "Boolean designating if you would like module instances where the course is timetabled to last for an entire academic year.", - "required": false, - "schema": { - "type": "boolean" - } - }, - { - "name": "lsr", - "in": "query", - "description": "Boolean designating if you would like module instances where the module is timetabled during the Late Summer Resit period. This is used internally by Examinations to timetable Late Summer Assessments (LSAs).", - "required": false, - "schema": { - "type": "boolean" - } - }, - { - "name": "is_summer_school", - "in": "query", - "description": "Boolean designating if you would like module instances where the course is taught as part of the UCL Summer School (true) or standard academic teaching (false).", - "required": false, - "schema": { - "type": "boolean" - } - }, - { - "name": "session_1", - "in": "query", - "description": "Boolean designating if you would like module instances where the module is taught in the first summer school session of this academic year's summer.", - "required": false, - "schema": { - "type": "boolean" + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "ok": { + "type": "boolean" + }, + "surveys": { + "type": "array", + "items": { + "$ref": "#/components/schemas/survey_with_maps" + } + } + } + } + } } }, - { - "name": "session_2", - "in": "query", - "description": "Boolean designating if you would like module instances where the module is taught in the second summer school session of this academic year's summer.", - "required": false, - "schema": { - "type": "boolean" + "400": { + "description": "Request error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/error" + }, + "examples": { + "1": { + "$ref": "#/components/examples/ErrorNoToken" + }, + "2": { + "$ref": "#/components/examples/ErrorTokenNotExist" + }, + "3": { + "$ref": "#/components/examples/ErrorInvalidToken" + }, + "4": { + "$ref": "#/components/examples/ErrorThrottling" + }, + "5": { + "$ref": "#/components/examples/ErrorNoClientSecret" + }, + "6": { + "$ref": "#/components/examples/ErrorInvalidClientSecret" + }, + "7": { + "$ref": "#/components/examples/ErrorInactiveToken" + }, + "Invalid filter": { + "value": { + "ok": false, + "error": "The survey filter you provided is invalid. Valid survey filters are: all,staff,student" + } + }, + "Invalid survey IDs": { + "value": { + "ok": false, + "error": "One or more of the survey_ids you requested is not valid." + } + } + } + } } - }, + } + } + } + }, + "/workspaces/images/map": { + "get": { + "summary": "Returns the image specified by the passed in image_id.", + "description": "Image IDs are provided by the /workspaces/surveys endpoint within the array of maps. Each map has an image.\n\nThe response will either be a JSON object if base64 is requested, as described below, or a raw object with the Content-Typeheader set to the content type.", + "tags": [ + "Workspaces" + ], + "parameters": [ { - "name": "is_undergraduate", + "name": "image_id", "in": "query", - "description": "Boolean designating if you would like undergraduate module instances.", - "required": false, + "description": "The ID of the image to obtain.", + "required": true, "schema": { - "type": "boolean" + "type": "number" } }, { - "name": "only_available", + "name": "image_format", "in": "query", - "description": "Boolean designating if you would only like available module instances (i.e. ones that are not compulsory for the course).", + "description": "The format of the response. This can either be base64, which returns a JSON object as shown in the example, or raw which will respond with a raw image. In the case of a raw image, the Content-Type header will define the data type, such as image/png.", "required": false, "schema": { - "type": "boolean" + "type": "string" } - }, + } + ], + "security": [ { - "name": "only_compulsory", - "in": "query", - "description": "Boolean designating if you would only like compulsory module instances.", - "required": false, - "schema": { - "type": "boolean" - } + "OAuthSecurity": [], + "OAuthToken": [] } ], "responses": { "200": { - "description": "A list of department objects.", + "description": "Success", "content": { "application/json": { "schema": { @@ -2130,11 +4293,13 @@ "ok": { "type": "boolean" }, - "modules": { - "type": "object", - "additionalProperties": { - "$ref": "#/components/schemas/module_data_courses_modules" - } + "content_type": { + "type": "string", + "example": "image/png" + }, + "data": { + "type": "string", + "example": "iVBORw0KGgoAAAANSUhEUgAAE2AAAAVOCAIAAAA..." } } } @@ -2170,22 +4335,22 @@ "7": { "$ref": "#/components/examples/ErrorInactiveToken" }, - "No course ID provided": { + "Missing image ID parameter": { "value": { "ok": false, - "error": "No course ID provided." + "error": "No Image ID provided." } }, - "Invalid paramenter type": { + "Invalid image ID": { "value": { "ok": false, - "error": "Given parameter is not of correct type" + "error": "The image with the ID you requested does not exist." } }, - "Invalid parameters": { + "Unsupported image format": { "value": { "ok": false, - "error": "only_available and only_compulsory cannot both be true" + "error": "You specified a response format that was not either raw or base64." } } } @@ -2195,78 +4360,137 @@ } } }, - "/oauth/authorise": { + "/workspaces/images/map/live": { "get": { - "summary": "Authorises a user against the API", - "description": "This endpoint should be used to authorise a user against the API.\n\nIt will perform a redirect if the user successfully logged in and accepted/denied the request.\n\nSee the below code samples for how you might implement this in your code.\n\nPython:\n```python\n url = \"https://uclapi.com/oauth/authorise/?client_id=123&state=1\"\n\n'''\n in a desktop app, script, or for testing\n'''\nimport webbrowser\nwebbrowser.open_new(url) \n# note that you will also need some way receive the callback\n# this can be done via a web server (e.g. below)\n\n'''\n on a Flask server\n this example covers both redirecting the user to\n the /authorise page and receiving the callback\n'''\nfrom flask import Flask, redirect, request\napp = Flask(__name__)\n\n@app.route('/login')\ndef uclapi_login():\n return redirect(url)\n\n@app.route('/callback')\ndef receive_callback():\n # receive parameters\n result = request.args.get('result', '')\n code = request.args.get('code', '')\n state = request.args.get('state', '')\n # do something with these parameters\n # e.g. request an auth token from /oauth/token\n return\n```\n\nShell:\n```shell\n # linux\n xdg-open \"https://uclapi.com/oauth/authorise/?client_id=123.456&state=1\"\n \n # WSL\n cmd.exe /c start \"https://uclapi.com/oauth/authorise/?client_id=123^&state=1\"\n\n # note that you will also need some way to receive the callback\n```\n\nJavaScript:\n```js\nconst url = \"https://uclapi.com/oauth/authorise/?client_id=123.456&state=1\"\n\n/* in-browser */\nwindow.location.href = url\n// note that you will also need some way to receive the callback\n// this can be done via a web server (e.g. below)\n\n/* Node.JS Express server */\nconst express = require('express')\nconst app = express()\n\napp.get('/login', (req, res) => res.redirect(url))\napp.get('/callback', (req, res) => {\n const {\n result,\n code,\n state\n } = req.params\n // do something with these parameters\n // e.g. request an auth token from /oauth/token\n})\n\napp.listen(3000)\n```", + "summary": "Takes Survey ID and Map ID as parameters and displays a dynamically generated SVG map.", + "description": "The SVG map is correct as of the time of the API call (aside from caching overhead), showing the map's plan image with a circle overlaid on each seat. This circle is coloured based on whether the seat is occupied or absent (e.g. it's free).\n\nThere are also several parameters that let you customise the map to suit your app or integration.", "tags": [ - "OAuth" + "Workspaces" + ], + "security": [ + { + "OAuthSecurity": [], + "OAuthToken": [] + } ], "parameters": [ { - "name": "client_id", + "$ref": "#/components/parameters/survey_id" + }, + { + "name": "map_id", "in": "query", - "description": "Client ID of the authenticating app.", + "description": "The ID of the library's survey which contains the map you want to obtain.", "required": true, "schema": { - "type": "string", - "example": "9020633324528794.9923205739531139" + "type": "number" } }, { - "name": "state", + "name": "image_scale", "in": "query", - "description": "OAuth (random) state.", - "required": true, + "description": "The SVG image's scale. The default is 0.02. The scale is implemented as an SVG transform scale, and is applied to both the x and the y axes of the image.", + "required": false, "schema": { - "type": "string", - "example": "jAifrW3" + "type": "number" + } + }, + { + "name": "circle_radius", + "in": "query", + "description": "The size of the circle. This must be a positive float value. The default is 128.", + "required": false, + "schema": { + "type": "number" + } + }, + { + "name": "absent_colour", + "in": "query", + "description": "TThe colour of the circle designating a free seat. This must be provided as a hex colour code, including the preceeding", + "required": false, + "schema": { + "type": "number" + } + }, + { + "name": "occupied_colour", + "in": "query", + "description": "The colour of the circle designating a taken, or occupied, seat. This must be provided as a hex colour code, including the preceeding", + "required": false, + "schema": { + "type": "number" } } ], "responses": { - "302": { - "description": "Redirection. See the expected query parameters in the URL description below.", - "headers": { - "Location": { - "description": "The redirection performed on success OR failure.\nThe URL will have the following query parameters:\n- `client_id` - the Client ID of the authentication app (e.g. `123456`)\n- `state` - the same state parameter originally sent as a query parameter to /oauth/authorise (e.g. `jAifrW3`)\n- `result` - either `allowed` or `denied` depending on whether the user granted permission\n- `code` - a secret code to be used to obtain an OAuth token via the /oauth/token endpoint (e.g. `mysecretcode`)", + "200": { + "description": "Success", + "content": { + "application/xml": { "schema": { - "type": "string", - "format": "uri" + "$ref": "#/components/schemas/svg" } } } }, "400": { - "description": "OAuth error", + "description": "Request error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" }, "examples": { - "Incorrect parameters supplied": { + "1": { + "$ref": "#/components/examples/ErrorNoToken" + }, + "2": { + "$ref": "#/components/examples/ErrorTokenNotExist" + }, + "3": { + "$ref": "#/components/examples/ErrorInvalidToken" + }, + "4": { + "$ref": "#/components/examples/ErrorThrottling" + }, + "5": { + "$ref": "#/components/examples/ErrorNoClientSecret" + }, + "6": { + "$ref": "#/components/examples/ErrorInvalidClientSecret" + }, + "7": { + "$ref": "#/components/examples/ErrorInactiveToken" + }, + "Missing parameters": { "value": { "ok": false, - "error": "You did not supply a client_id and a state in your request." + "error": "You must provide a Survey ID and a Map ID to get a live sensor status image." } }, - "App does not exist for client id": { + "Invalid colours": { "value": { "ok": false, - "error": "You supplied an invalid client_id." + "error": "The custom colours you specified did not match the formal of HTML hex colours. Colours must either be in the format #ABC or #ABCDEF." } }, - "No callback URL set for this app": { + "Invalid scale": { "value": { "ok": false, - "error": "You did not set a callback URL for your app." + "error": "The scale you specified is not valid. It must be a floating point number, such as 1 or 0.02." } }, - "UCL has sent incomplete headers": { + "Invalid circle radius": { "value": { "ok": false, - "error": "UCL sent us incomplete headers. If the issue persists, please contact the UCL API Team." + "error": "The circle radius you specified is not valid. It must be a floating point number, such as 128 or 100.5." + } + }, + "Invalid survey IDs": { + "value": { + "ok": false, + "error": "Either the IDs you sent were not integers, or they do not exist." } } } @@ -2276,40 +4500,43 @@ } } }, - "/oauth/token": { + "/workspaces/historical/data": { "get": { - "summary": "A token will be generated which your app can use to get user’s personal data in JSON format from the OAuthSecurity/user/data.", - "description": "This endpoint should be used to obtain a token for use in the other API endpoints.\n\nSee the below code samples for how you might implement this in your code.\n\nPython:\n```python\nimport requests\n\nparams = {\n \"client_id\": \"123.456\",\n \"code\": \"1\",\n \"client_secret\": \"secret\",\n}\nr = requests.get(\"https://uclapi.com/oauth/token\", params=params)\nprint(r.json())\n```\n\nShell:\n```shell\ncurl -G https://uclapi.com/oauth/token -d code=mysecretcode -d client_id=123.456 -d client_secret=secret\n```\n\nJavaScript:\n```js\nfetch(\"https://uclapi.com/oauth/token?code=mysecretcode&client_id=123.456&client_secret=secret\")\n .then(response => response.json())\n .then(json => console.log(json));\n```", + "summary": "List Historical Data", + "description": "This endpoint provides historical sensor readings for all sensors in all survey locations. This must be restricted to a single survey location with survey_id and can be optionally restricted to a single sensor with sensor_id.\n\nTo specify a start time datetime__gte (datetime greater than or equal to) and for an end time datetime__lte (datetime less than or equal to) can be used. The deltas (changes) of a sensor will be returned.\n\nConforms to CursorPagination from Django REST.\n\nThis endpoint will return a dictionary of every sensor reading in the time range.", "tags": [ - "OAuth" + "Workspaces" ], - "security": [ + "parameters": [ + { + "$ref": "#/components/parameters/cursor" + }, + { + "$ref": "#/components/parameters/survey_id" + }, + { + "$ref": "#/components/parameters/sensor_id" + }, { - "OAuthSecurity": [] - } - ], - "parameters": [ + "$ref": "#/components/parameters/datetime__gte" + }, { - "$ref": "#/components/parameters/client_secret" + "$ref": "#/components/parameters/datetime__lte" }, { - "name": "client_id", - "in": "query", - "description": "Client ID of the authenticating app.", - "required": true, - "schema": { - "type": "string", - "example": "9020633324528794.9923205739531139" - } + "$ref": "#/components/parameters/datetime__exact" }, { - "name": "code", - "in": "query", - "description": "Secret code obtained from the authorise endpoint.", - "required": true, - "schema": { - "type": "string" - } + "$ref": "#/components/parameters/datetime__gt" + }, + { + "$ref": "#/components/parameters/datetime__lt" + } + ], + "security": [ + { + "OAuthSecurity": [], + "OAuthToken": [] } ], "responses": { @@ -2323,20 +4550,24 @@ "ok": { "type": "boolean" }, - "state": { - "type": "string" - }, - "scope": { - "type": "array", - "items": { - "type": "string" + "data": { + "type": "object", + "properties": { + "next": { + "type": "string", + "example": null + }, + "previous": { + "type": "string", + "example": null + }, + "results": { + "type": "array", + "items": { + "$ref": "#/components/schemas/historical_survey_data" + } + } } - }, - "client_id": { - "type": "string" - }, - "token": { - "type": "string" } } } @@ -2344,36 +4575,33 @@ } }, "400": { - "description": "OAuth error", + "description": "Request error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" }, "examples": { - "Incomplete data": { - "value": { - "ok": false, - "error": "The client did not provide the requisite data to get a token." - } + "1": { + "$ref": "#/components/examples/ErrorNoToken" }, - "Invalid/Expired code": { - "value": { - "ok": false, - "error": "The code received was invalid, or has expired. Please try again." - } + "2": { + "$ref": "#/components/examples/ErrorTokenNotExist" }, - "Non-existent client": { - "value": { - "ok": false, - "error": "App has been deleted or the Client ID is invalid." - } + "3": { + "$ref": "#/components/examples/ErrorInvalidToken" }, - "Invalid client secret": { - "value": { - "ok": false, - "error": "Client secret incorrect" - } + "4": { + "$ref": "#/components/examples/ErrorThrottling" + }, + "5": { + "$ref": "#/components/examples/ErrorNoClientSecret" + }, + "6": { + "$ref": "#/components/examples/ErrorInvalidClientSecret" + }, + "7": { + "$ref": "#/components/examples/ErrorInactiveToken" } } } @@ -2382,21 +4610,28 @@ } } }, - "/oauth/user/data": { + "/workspaces/historical/sensors": { "get": { - "summary": "Returns personal data on a student at UCL.", + "summary": "List Historical Sensors", + "description": "This endpoint lists all sensors in a survey location, this includes inactive sensors (unlike get sensors from workspaces).\n\nConforms to StandardResultsSetPagination from Django REST.\n\nThis endpoint will return a list of every sensor.", "tags": [ - "OAuth" + "Workspaces" ], - "security": [ + "parameters": [ { - "OAuthSecurity": [], - "OAuthToken": [] + "$ref": "#/components/parameters/page" + }, + { + "$ref": "#/components/parameters/survey_id" + }, + { + "$ref": "#/components/parameters/sensor_id" } ], - "parameters": [ + "security": [ { - "$ref": "#/components/parameters/client_secret" + "OAuthSecurity": [], + "OAuthToken": [] } ], "responses": { @@ -2405,13 +4640,41 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/user_data" + "type": "object", + "properties": { + "ok": { + "type": "boolean" + }, + "data": { + "type": "object", + "properties": { + "next": { + "type": "string", + "example": "https://uclapi.com/workspaces/historical/sensors?page=2" + }, + "previous": { + "type": "string", + "example": null + }, + "count": { + "type": "integer", + "example": 17936 + }, + "results": { + "type": "array", + "items": { + "$ref": "#/components/schemas/historical_sensor" + } + } + } + } + } } } } }, "400": { - "description": "OAuth error", + "description": "Request error", "content": { "application/json": { "schema": { @@ -2422,7 +4685,7 @@ "$ref": "#/components/examples/ErrorNoToken" }, "2": { - "$ref": "#/components/examples/ErrorInvalidClientSecret" + "$ref": "#/components/examples/ErrorTokenNotExist" }, "3": { "$ref": "#/components/examples/ErrorInvalidToken" @@ -2438,9 +4701,6 @@ }, "7": { "$ref": "#/components/examples/ErrorInactiveToken" - }, - "8": { - "$ref": "#/components/examples/ErrorPersonalData" } } } @@ -2449,24 +4709,28 @@ } } }, - "/oauth/user/studentnumber": { + "/workspaces/historical/surveys": { "get": { - "summary": "You can use the oauth/user/data endpoint to find out whether the user is a student before you call this endpoint. If you call this endpoint and the user is not a student, an error will be returned.", - "description": "Please note: to use this endpoint you must have ticked the Student Number scope for your application in the Dashboard. This piece of information has been separated from the others because a student number can in some cases be considered confidential. This is because any data exported directly from Portico, SITS (E:Vision) or CMIS is usually grouped by Student Number. One example is that in some cases departments choose to release spreadsheets of examination results where each student is identified by their student number, and not their name, to provide a degree of anonymity in what is otherwise an open data set. You should consider carefully whether you actually need a student number to track students when other unique identifiers are available, such as their username-based email address and UPI. If you request a student number and it is not required for your application, your users may choose not to provide this information to you, and therefore deny your application permission to access their details.", + "summary": "List Historical Surveys", + "description": "This endpoint lists all historical survey locations, this includes inactive survey locations (unlike get survey from workspaces).\n\nConforms to StandardResultsSetPagination from Django REST.", "tags": [ - "OAuth" + "Workspaces" ], - "security": [ + "parameters": [ { - "OAuthSecurity": [ - "student_number" - ], - "OAuthToken": [] + "$ref": "#/components/parameters/page" + }, + { + "$ref": "#/components/parameters/survey_id" + }, + { + "$ref": "#/components/parameters/active" } ], - "parameters": [ + "security": [ { - "$ref": "#/components/parameters/client_secret" + "OAuthSecurity": [], + "OAuthToken": [] } ], "responses": { @@ -2480,8 +4744,28 @@ "ok": { "type": "boolean" }, - "student_number": { - "type": "string" + "surveys": { + "type": "object", + "properties": { + "next": { + "type": "string", + "example": "https://uclapi.com/workspaces/historical/sensors?page=2" + }, + "previous": { + "type": "string", + "example": null + }, + "count": { + "type": "integer", + "example": 17936 + }, + "results": { + "type": "array", + "items": { + "$ref": "#/components/schemas/historical_survey" + } + } + } } } } @@ -2489,7 +4773,7 @@ } }, "400": { - "description": "OAuth error", + "description": "Request error", "content": { "application/json": { "schema": { @@ -2500,7 +4784,7 @@ "$ref": "#/components/examples/ErrorNoToken" }, "2": { - "$ref": "#/components/examples/ErrorInvalidClientSecret" + "$ref": "#/components/examples/ErrorTokenNotExist" }, "3": { "$ref": "#/components/examples/ErrorInvalidToken" @@ -2516,15 +4800,6 @@ }, "7": { "$ref": "#/components/examples/ErrorInactiveToken" - }, - "8": { - "$ref": "#/components/examples/ErrorRejectedScope" - }, - "User is not a student": { - "value": { - "ok": false, - "error": "User is not a student." - } } } } @@ -2533,37 +4808,16 @@ } } }, - "/roombookings/rooms": { + "/dashboard/api/analytics/total": { "get": { - "summary": "Returns rooms and information about them.", - "description": "If you don’t specify any query parameters besides the token, all rooms will be returned.\n\nNote: This endpoint only returns publicly bookable rooms. Departmentally bookable rooms are not included. In the response, the room field contains a list of rooms that match your query. If no filters are applied, all rooms will be returned.", + "summary": "Gets the total number of requests made from a given token", "tags": [ - "Room Bookings" + "Analytics" ], "security": [ { - "OAuthSecurity": [], - "OAuthToken": [] - } - ], - "parameters": [ - { - "$ref": "#/components/parameters/roomname" - }, - { - "$ref": "#/components/parameters/roomid" - }, - { - "$ref": "#/components/parameters/siteid" - }, - { - "$ref": "#/components/parameters/sitename" - }, - { - "$ref": "#/components/parameters/classification" - }, - { - "$ref": "#/components/parameters/capacity" + "OAuthSecurity": [], + "OAuthToken": [] } ], "responses": { @@ -2577,11 +4831,8 @@ "ok": { "type": "boolean" }, - "rooms": { - "type": "array", - "items": { - "$ref": "#/components/schemas/room" - } + "num": { + "type": "number" } } } @@ -2607,21 +4858,6 @@ }, "4": { "$ref": "#/components/examples/ErrorThrottling" - }, - "5": { - "$ref": "#/components/examples/ErrorNoClientSecret" - }, - "6": { - "$ref": "#/components/examples/ErrorInvalidClientSecret" - }, - "7": { - "$ref": "#/components/examples/ErrorInactiveToken" - }, - "Invalid capacity": { - "value": { - "ok": false, - "error": "capacity should always be an int" - } } } } @@ -2630,12 +4866,11 @@ } } }, - "/roombookings/bookings": { + "/dashboard/api/analytics/quota": { "get": { - "summary": "Returns the results to a bookings or space availability query. It returns a paginated list of bookings.", - "description": "Note: This endpoint only returns publicly bookable rooms. Departmentally bookable rooms are not included.", + "summary": "Gets the remaining daily quota for a given token", "tags": [ - "Room Bookings" + "Analytics" ], "security": [ { @@ -2643,35 +4878,6 @@ "OAuthToken": [] } ], - "parameters": [ - { - "$ref": "#/components/parameters/roomname" - }, - { - "$ref": "#/components/parameters/roomid" - }, - { - "$ref": "#/components/parameters/start_datetime" - }, - { - "$ref": "#/components/parameters/end_datetime" - }, - { - "$ref": "#/components/parameters/date" - }, - { - "$ref": "#/components/parameters/siteid" - }, - { - "$ref": "#/components/parameters/description" - }, - { - "$ref": "#/components/parameters/contact" - }, - { - "$ref": "#/components/parameters/results_per_page" - } - ], "responses": { "200": { "description": "Success", @@ -2683,20 +4889,8 @@ "ok": { "type": "boolean" }, - "next_page_exists": { - "type": "boolean" - }, - "page_token": { - "type": "string" - }, - "count": { + "remaining": { "type": "number" - }, - "bookings": { - "type": "array", - "items": { - "$ref": "#/components/schemas/booking" - } } } } @@ -2731,23 +4925,96 @@ }, "7": { "$ref": "#/components/examples/ErrorInactiveToken" - }, - "Invalid date/time": { - "value": { - "ok": false, - "error": "start_datetime/end_datetime isn't formatted as suggested in the docs" - } - }, - "Invalid results_per_page": { - "value": { - "ok": false, - "error": "results_per_page should be an integer" + } + } + } + } + } + } + } + }, + "/dashboard/api/analytics/services": { + "get": { + "summary": "Gets all services and their popularity", + "tags": [ + "Analytics" + ], + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "ok": { + "type": "boolean" + }, + "data": { + "type": "array", + "items": { + "type": "object", + "properties": { + "service": { + "type": "string", + "example": "roombookings" + }, + "count": { + "type": "integer" + } + } + } } - }, - "Non-existent page token": { - "value": { - "ok": false, - "error": "Page token does not exist" + } + } + } + } + } + } + } + }, + "/dashboard/api/analytics/methods": { + "get": { + "summary": "Gets all methods for a given service and their popularity", + "tags": [ + "Analytics" + ], + "parameters": [ + { + "name": "service", + "in": "query", + "description": "The service to check the popularity of methods for", + "required": false, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "ok": { + "type": "boolean" + }, + "data": { + "type": "array", + "items": { + "type": "object", + "properties": { + "method": { + "type": "string", + "example": "rooms" + }, + "count": { + "type": "integer" + } + } + } } } } @@ -2757,12 +5024,11 @@ } } }, - "/roombookings/equipment": { + "/dashboard/api/analytics/oauth/total": { "get": { - "summary": "Returns any equipment/feature information about a specific room.", - "description": "So, for example whether there is a Whiteboard or a DVD Player in the room. A full example can be seen here.", + "summary": "Gets the total number of users for a given app token", "tags": [ - "Room Bookings" + "Analytics" ], "security": [ { @@ -2772,10 +5038,22 @@ ], "parameters": [ { - "$ref": "#/components/parameters/roomid" + "name": "start_date", + "in": "query", + "description": "Start date to filter by", + "required": false, + "schema": { + "type": "string" + } }, { - "$ref": "#/components/parameters/siteid" + "name": "end_date", + "in": "query", + "description": "End date to filter by", + "required": false, + "schema": { + "type": "string" + } } ], "responses": { @@ -2789,11 +5067,8 @@ "ok": { "type": "boolean" }, - "equipment": { - "type": "array", - "items": { - "$ref": "#/components/schemas/equipment" - } + "users": { + "type": "integer" } } } @@ -2810,36 +5085,6 @@ "examples": { "1": { "$ref": "#/components/examples/ErrorNoToken" - }, - "2": { - "$ref": "#/components/examples/ErrorTokenNotExist" - }, - "3": { - "$ref": "#/components/examples/ErrorInvalidToken" - }, - "4": { - "$ref": "#/components/examples/ErrorThrottling" - }, - "5": { - "$ref": "#/components/examples/ErrorNoClientSecret" - }, - "6": { - "$ref": "#/components/examples/ErrorInvalidClientSecret" - }, - "7": { - "$ref": "#/components/examples/ErrorInactiveToken" - }, - "Invalid roomid": { - "value": { - "ok": false, - "error": "No roomid supplied" - } - }, - "Invalid siteid": { - "value": { - "ok": false, - "error": "No siteid supplied" - } } } } @@ -2848,25 +5093,16 @@ } } }, - "/roombookings/freerooms": { + "/dashboard/api/analytics/oauth/total_by_dept": { "get": { - "summary": "Given a start time and an end time, this endpoint returns all rooms which are free in that time range.", - "description": "Note: This endpoint only returns publicly bookable rooms. Departmentally bookable rooms are not included.", + "summary": "Gets the total number of users for a given app token, by department", "tags": [ - "Room Bookings" + "Analytics" ], "security": [ { - "OAuthSecurity": [], - "OAuthToken": [] - } - ], - "parameters": [ - { - "$ref": "#/components/parameters/start_datetime" - }, - { - "$ref": "#/components/parameters/end_datetime" + "OAuthSecurity": [], + "OAuthToken": [] } ], "responses": { @@ -2880,13 +5116,19 @@ "ok": { "type": "boolean" }, - "count": { - "type": "integer" - }, - "free_rooms": { + "data": { "type": "array", "items": { - "$ref": "#/components/schemas/room" + "type": "object", + "properties": { + "department": { + "type": "string", + "example": "Dept of Computer Science" + }, + "count": { + "type": "integer" + } + } } } } @@ -2904,36 +5146,6 @@ "examples": { "1": { "$ref": "#/components/examples/ErrorNoToken" - }, - "2": { - "$ref": "#/components/examples/ErrorTokenNotExist" - }, - "3": { - "$ref": "#/components/examples/ErrorInvalidToken" - }, - "4": { - "$ref": "#/components/examples/ErrorThrottling" - }, - "5": { - "$ref": "#/components/examples/ErrorNoClientSecret" - }, - "6": { - "$ref": "#/components/examples/ErrorInvalidClientSecret" - }, - "7": { - "$ref": "#/components/examples/ErrorInactiveToken" - }, - "Invalid parameters": { - "value": { - "ok": false, - "error": "start_datetime or end_datetime not provided" - } - }, - "Invalid date/time": { - "value": { - "ok": false, - "error": "start_datetime/end_datetime isn't formatted as suggested in the docs" - } } } } @@ -2942,28 +5154,20 @@ } } }, - "/search/people": { + "/libcal/space/locations": { "get": { - "summary": "Returns matching people and information about them.", - "description": "Note that this endpoint only returns a maximum of 20 matches.\n\nFollowing a change to UCL's systems in 2019, this endpoint only returns staff; students will not be returned through this API.", + "summary": "Gets all LibCal locations", "tags": [ - "Search" + "LibCal" ], - "security": [ + "parameters": [ { - "OAuthSecurity": [], - "OAuthToken": [] + "$ref": "#/components/parameters/libcal_details" } ], - "parameters": [ + "security": [ { - "name": "query", - "in": "query", - "description": "Name of the person you are searching for.", - "required": true, - "schema": { - "type": "string" - } + "ApiToken": [] } ], "responses": { @@ -2977,10 +5181,10 @@ "ok": { "type": "boolean" }, - "people": { + "data": { "type": "array", "items": { - "$ref": "#/components/schemas/person" + "$ref": "#/components/schemas/libcal_location" } } } @@ -3017,11 +5221,14 @@ "7": { "$ref": "#/components/examples/ErrorInactiveToken" }, - "Invalid query": { - "value": { - "ok": false, - "error": "No query provided" - } + "8": { + "$ref": "#/components/examples/ErrorPersonalData" + }, + "9": { + "$ref": "#/components/examples/ErrorRejectedScope" + }, + "10": { + "$ref": "#/components/examples/ErrorLibCalOAuthTokenInvalid" } } } @@ -3030,16 +5237,20 @@ } } }, - "/resources/desktops": { + "/libcal/space/categories": { "get": { - "summary": "Returns number of desktops and how many are free at the time of making the request.", + "summary": "Returns the categories of spaces available in the given location(s)", "tags": [ - "Resources" + "LibCal" ], "security": [ { - "OAuthSecurity": [], - "OAuthToken": [] + "ApiToken": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/libcal_location_ids" } ], "responses": { @@ -3053,10 +5264,22 @@ "ok": { "type": "boolean" }, - "data": { + "categories": { "type": "array", "items": { - "$ref": "#/components/schemas/desktop_data" + "allOf": [ + { + "$ref": "#/components/schemas/libcal_location_base" + } + ], + "properties": { + "categories": { + "type": "array", + "items": { + "$ref": "#/components/schemas/libcal_category" + } + } + } } } } @@ -3093,17 +5316,14 @@ "7": { "$ref": "#/components/examples/ErrorInactiveToken" }, - "Error retrieving data": { - "value": { - "ok": false, - "error": "Could not retrieve availability data. Please try again later or contact us for support." - } + "8": { + "$ref": "#/components/examples/ErrorPersonalData" }, - "Error parsing data": { - "value": { - "ok": false, - "error": "Could not parse the desktop availability data. Please try again later or contact us for support." - } + "9": { + "$ref": "#/components/examples/ErrorRejectedScope" + }, + "10": { + "$ref": "#/components/examples/ErrorLibCalOAuthTokenInvalid" } } } @@ -3112,22 +5332,26 @@ } } }, - "/workspaces/surveys": { + "/libcal/space/category": { "get": { - "summary": "Returns all UCL libraries with the Cad-Capture devices fitted to the seats", - "description": "Each library is known as a 'survey', as it is a survey of the building. Within each survey there are multiple 'maps', each of which corresponds to a section such as a level, wing or separated library work area. Each sensor is tied to a specific map, and each map belongs to a survey.\n\nThe surveys key contains a list of dictionaries, each of which corresponds to a library survey with seating sensors attached. Each survey has a number of maps, corresponding to regions within the library, such as a different floor or wing. Note that the location[address] field will not always contain a precise address, and may simply contain the address to the UCL campus (i.e. Gower Street, London), which may not be helpful. If it is present, the location[coordinates] will generally be more precise.", + "summary": "Get all spaces corresponding to the specified categories", "tags": [ - "Workspaces" + "LibCal" ], - "security": [ + "parameters": [ { - "OAuthSecurity": [], - "OAuthToken": [] + "$ref": "#/components/parameters/libcal_category_ids" + }, + { + "$ref": "#/components/parameters/libcal_details" + }, + { + "$ref": "#/components/parameters/libcal_availability" } ], - "parameters": [ + "security": [ { - "$ref": "#/components/parameters/survey_filter" + "ApiToken": [] } ], "responses": { @@ -3141,10 +5365,29 @@ "ok": { "type": "boolean" }, - "surveys": { + "categories": { "type": "array", "items": { - "$ref": "#/components/schemas/survey" + "type": "object", + "properties": { + "cid": { + "$ref": "#/components/schemas/libcal_category_id" + }, + "formid": { + "$ref": "#/components/schemas/libcal_form_id" + }, + "public": { + "$ref": "#/components/schemas/libcal_category_public" + }, + "items": { + "type": "array", + "items": { + "type": "integer", + "description": "LibCal Space ID", + "example": 11903 + } + } + } } } } @@ -3181,11 +5424,14 @@ "7": { "$ref": "#/components/examples/ErrorInactiveToken" }, - "Invalid filter": { - "value": { - "ok": false, - "error": "The survey filter you provided is invalid. Valid survey filters are: all,staff,student" - } + "8": { + "$ref": "#/components/examples/ErrorPersonalData" + }, + "9": { + "$ref": "#/components/examples/ErrorRejectedScope" + }, + "10": { + "$ref": "#/components/examples/ErrorLibCalOAuthTokenInvalid" } } } @@ -3194,31 +5440,20 @@ } } }, - "/workspaces/sensors": { + "/libcal/space/form": { "get": { - "summary": "Provides a list of every sensor within every map in a survey/library.", - "description": "It can optionally provide the current state of a sensor (e.g. Occupied / Absent), but by default it will only list the sensors without their states.\n\nThis endpoint will return a list of every map within a survey, and within it every sensor associated with that map. It will optionally also return the latest triggered state of that sensor (e.g. whether the seat was marked triggered or occupied).\n\nNote that the following response data table is deliberately incomplete. This is because we return additional metadata that is not yet useful, and often left blank by the provider. We will update this documentation if and when these extra parameters become useful.", + "summary": "Get all forms (including fields) corresponding to the given LibCal form ID(s)", "tags": [ - "Workspaces" + "LibCal" ], - "security": [ + "parameters": [ { - "OAuthSecurity": [], - "OAuthToken": [] + "$ref": "#/components/parameters/libcal_form_ids" } ], - "parameters": [ - { - "$ref": "#/components/parameters/survey_id" - }, + "security": [ { - "name": "return_states", - "in": "query", - "description": "Whether or not to return the latest trigger state of each sensor. Defaults to false. For live data, set this to true.", - "required": false, - "schema": { - "type": "boolean" - } + "ApiToken": [] } ], "responses": { @@ -3232,16 +5467,10 @@ "ok": { "type": "boolean" }, - "survey_name": { - "type": "string" - }, - "survey_id": { - "type": "number" - }, - "maps": { + "forms": { "type": "array", "items": { - "$ref": "#/components/schemas/map_with_sensors" + "$ref": "#/components/schemas/libcal_form" } } } @@ -3278,17 +5507,14 @@ "7": { "$ref": "#/components/examples/ErrorInactiveToken" }, - "Missing parameter": { - "value": { - "ok": false, - "error": "Please specify a survey_id." - } + "8": { + "$ref": "#/components/examples/ErrorPersonalData" }, - "Invalid parameter": { - "value": { - "ok": false, - "error": "The survey_id you specified was not valid." - } + "9": { + "$ref": "#/components/examples/ErrorRejectedScope" + }, + "10": { + "$ref": "#/components/examples/ErrorLibCalOAuthTokenInvalid" } } } @@ -3297,34 +5523,20 @@ } } }, - "/workspaces/sensors/averages/time": { + "/libcal/space/question": { "get": { - "summary": "Provides a list of every sensor within every map in a survey/library.", - "description": " It can optionally provide the current state of a sensor (e.g. Occupied / Absent), but by default it will only list the sensors without their states.\n\nThis endpoint will show for every survey_id provided the average utilisation of the associated library at ten minute intervals throughout the day. This can be used, for example, in apps and integrations which show users how busy each library is at given times of the day. You can show data based on the last day (e.g. yesterday), the last week or the last month. Each day's data is updated in the early hours of the morning (around 2am) so that users during the day have the latest data.\n\nThis endpoint will return a list with every survey requested, its ID, its name and average data for the period requested for every 10 minute period in a day. The averages are not ordered, so it is recommended that the data is fed into some other code to transform the data in such as way as to ensure that it is user-friendly. One example might be a graphing library to plot the data throughout the day to produce an average occupancy graph.\n\nPlease note that the counts below may not perfectly add up. This is because we perform an integer division calculation to get an average based on multiple days' worth of data, so you may encounter off-by-one errors if you check that sensors_absent + sensors_occupied == sensors_total. Please do not be alarmed by this! However, if you do get large, unexplained differences do let us know so that we can look into it.\n\nPlease note further that there are some rare situations where the data source we use may have historical data missing. Sitautions that can cause this include new libraries being added which do not yet have historical data available, and situations where data has not properly been saved by our data provider. In cases like this, our response to your app will include an empty averages object with no times within it. Your code should account for this possibility by checking whether each time period is actually present. If time periods are missing your application should alert the user to data being missing and fail gracefully.", + "summary": "Get the questions corresponding to the given LibCal field/question ID(s)", "tags": [ - "Workspaces" + "LibCal" ], - "security": [ + "parameters": [ { - "OAuthSecurity": [], - "OAuthToken": [] + "$ref": "#/components/parameters/libcal_field_ids" } ], - "parameters": [ - { - "name": "days", - "in": "query", - "description": "An integer number of days (either 1, 7 or 30) from which to deliver average data. The format of the data returned does not change based on this value, but the actual averaged figures do. When days is 1, the API will return the data from the previous complete day; when days is 7 the API will return data from the last week and when it is set to 30 the API will return data from the last 30 days, which is approx. one month.", - "required": true, - "schema": { - "type": "string" - } - }, - { - "$ref": "#/components/parameters/survey_ids" - }, + "security": [ { - "$ref": "#/components/parameters/survey_filter" + "ApiToken": [] } ], "responses": { @@ -3338,10 +5550,10 @@ "ok": { "type": "boolean" }, - "surveys": { + "questions": { "type": "array", "items": { - "$ref": "#/components/schemas/sensor_average_survey" + "$ref": "#/components/schemas/libcal_form_field" } } } @@ -3378,35 +5590,14 @@ "7": { "$ref": "#/components/examples/ErrorInactiveToken" }, - "Invalid filter": { - "value": { - "ok": false, - "error": "The survey filter you provided is invalid. Valid survey filters are: all,staff,student" - } - }, - "Missing days parameter": { - "value": { - "ok": false, - "error": "You did not specify how many days of historical data should be returned. Valid options are: 1,7,30" - } - }, - "Invalid days parameter": { - "value": { - "ok": false, - "error": "You did not specify an integer number of days of historical days, Valid options are: 1,7,30" - } + "8": { + "$ref": "#/components/examples/ErrorPersonalData" }, - "Unsupported days parameter": { - "value": { - "ok": false, - "error": "You did not specify a valid number of days of historical days, Valid options are: 1,7,30" - } + "9": { + "$ref": "#/components/examples/ErrorRejectedScope" }, - "Invalid survey IDs": { - "value": { - "ok": false, - "error": "One or more of the survey_ids you requested is not valid." - } + "10": { + "$ref": "#/components/examples/ErrorLibCalOAuthTokenInvalid" } } } @@ -3415,22 +5606,23 @@ } } }, - "/workspaces/sensors/lastupdated": { + "/libcal/space/item": { "get": { - "summary": "Replies with the timestamp of the last time the sensor data was updated for a given survey.", - "description": "This allows integrations that poll the API to save on request time by only requesting the full set of sensor information for a survey once it has been updated.", + "summary": "Get the spaces corresponding to the given LibCal space ID(s)", "tags": [ - "Workspaces" + "LibCal" ], - "security": [ + "parameters": [ { - "OAuthSecurity": [], - "OAuthToken": [] + "$ref": "#/components/parameters/libcal_space_ids" + }, + { + "$ref": "#/components/parameters/libcal_availability" } ], - "parameters": [ + "security": [ { - "$ref": "#/components/parameters/survey_id" + "ApiToken": [] } ], "responses": { @@ -3444,13 +5636,40 @@ "ok": { "type": "boolean" }, - "last_updated": { - "type": "string", - "example": "2018-02-16T15:33:01" - }, - "survey_id": { - "type": "number", - "example": "46" + "questions": { + "type": "array", + "items": { + "allOf": [ + { + "$ref": "#/components/schemas/libcal_space_base" + } + ], + "properties": { + "error": { + "type": "string", + "description": "Will be returned if there is an error retrieving the given LibCal space, e.g. if the space ID provided is invalid", + "example": "invalid item id" + }, + "is_bookable_as_whole": { + "type": "boolean", + "description": "Whether the entire LibCal zone can be booked as a whole", + "example": false + }, + "is_accessible": { + "type": "boolean", + "description": "Whether the furniture in the space is height-adjustable and hence accessible by the differently-abled", + "example": true + }, + "is_powered": { + "type": "boolean", + "description": "Whether a power socket is available at the space", + "example": true + }, + "zone_id": { + "$ref": "#/components/schemas/libcal_zone_id" + } + } + } } } } @@ -3486,17 +5705,14 @@ "7": { "$ref": "#/components/examples/ErrorInactiveToken" }, - "Missing survey ID": { - "value": { - "ok": false, - "error": "Please specify a survey_id" - } + "8": { + "$ref": "#/components/examples/ErrorPersonalData" }, - "Invalid survey ID": { - "value": { - "ok": false, - "error": "The survey_id you specified is not valid." - } + "9": { + "$ref": "#/components/examples/ErrorRejectedScope" + }, + "10": { + "$ref": "#/components/examples/ErrorLibCalOAuthTokenInvalid" } } } @@ -3505,25 +5721,23 @@ } } }, - "/workspaces/sensors/summary": { + "/libcal/space/nickname": { "get": { - "summary": "Summarises, with a one-minute accuracy, the number of seats within each library region that are free and occupied.", - "description": "It is best suited to integrations which show cumulative, live data. Developers can use this endpoint to avoid making many parallel or sequential requests to fetch survey sensor counts.\n\nThis endpoint takes into account UCL's thirty minute rule, which allows students to leave their seat unattended for up to thirty minutes at a time (e.g. to use the bathroom or get food). This means that the Summary endpoint may return a lower number of available seats when compared to reality if many students leave the library within a short period of time. The UCL Library's website and the UCL Go! mobile application both follow this rule, so your app or integration should have parity with first party data sources by using the UCL API.\n\nThis endpoint will return a list with every survey requested, and its associated maps. Within each map is a count of absent (i.e. vacant) and occupied seats. The endpoint also returns the total number of seats in each library that are absent or occupied.\n\nIf your application or integration is designed to inform students of the total number of free seats in a library please ensure you use the survey total figures. This is because many sensors have not yet been assigned to maps on our data provider's system which means that relying only on map counts will leave many seats unaccounted for. We are actively working with our data provider to rectify this, and we apologise for any inconvenience caused.", + "summary": "Get the nicknames asssigned to certain LibCal bookings", "tags": [ - "Workspaces" + "LibCal" ], "parameters": [ { - "$ref": "#/components/parameters/survey_ids" + "$ref": "#/components/parameters/libcal_category_ids" }, { - "$ref": "#/components/parameters/survey_filter" + "$ref": "#/components/parameters/libcal_availability" } ], "security": [ { - "OAuthSecurity": [], - "OAuthToken": [] + "ApiToken": [] } ], "responses": { @@ -3537,10 +5751,43 @@ "ok": { "type": "boolean" }, - "surveys": { + "categories": { "type": "array", "items": { - "$ref": "#/components/schemas/survey_with_maps" + "properties": { + "error": { + "type": "string", + "description": "Will be returned if there is an error retrieving the given LibCal space, e.g. if the space ID provided is invalid", + "example": "Public Nick Names are not enabled for this category" + }, + "cid": { + "$ref": "#/components/schemas/libcal_category_id" + }, + "name": { + "$ref": "#/components/schemas/libcal_category_name" + }, + "nickname_label": { + "type": "string", + "example": "Booking Label", + "description": "Describes the nature of the nicknames assigned to the bookings" + }, + "spaces": { + "properties": { + "id": { + "$ref": "#/components/schemas/libcal_space_id" + }, + "name": { + "$ref": "#/components/schemas/libcal_space_name" + }, + "bookings": { + "type": "array", + "items": { + "$ref": "#/components/schemas/libcal_booking" + } + } + } + } + } } } } @@ -3577,17 +5824,14 @@ "7": { "$ref": "#/components/examples/ErrorInactiveToken" }, - "Invalid filter": { - "value": { - "ok": false, - "error": "The survey filter you provided is invalid. Valid survey filters are: all,staff,student" - } + "8": { + "$ref": "#/components/examples/ErrorPersonalData" }, - "Invalid survey IDs": { - "value": { - "ok": false, - "error": "One or more of the survey_ids you requested is not valid." - } + "9": { + "$ref": "#/components/examples/ErrorRejectedScope" + }, + "10": { + "$ref": "#/components/examples/ErrorLibCalOAuthTokenInvalid" } } } @@ -3596,37 +5840,27 @@ } } }, - "/workspaces/images/map": { + "/libcal/space/utilization": { "get": { - "summary": "Returns the image specified by the passed in image_id.", - "description": "Image IDs are provided by the /workspaces/surveys endpoint within the array of maps. Each map has an image.\n\nThe response will either be a JSON object if base64 is requested, as described below, or a raw object with the Content-Typeheader set to the content type.", + "summary": "Get utilisation stats for a particular location", + "description": "Optionally filter by categoryId and zoneId", "tags": [ - "Workspaces" + "LibCal" ], "parameters": [ { - "name": "image_id", - "in": "query", - "description": "The ID of the image to obtain.", - "required": true, - "schema": { - "type": "number" - } + "$ref": "#/components/parameters/libcal_location_id" }, { - "name": "image_format", - "in": "query", - "description": "The format of the response. This can either be base64, which returns a JSON object as shown in the example, or raw which will respond with a raw image. In the case of a raw image, the Content-Type header will define the data type, such as image/png.", - "required": false, - "schema": { - "type": "string" - } + "$ref": "#/components/parameters/libcal_category_id" + }, + { + "$ref": "#/components/parameters/libcal_zone_id" } ], "security": [ { - "OAuthSecurity": [], - "OAuthToken": [] + "ApiToken": [] } ], "responses": { @@ -3640,13 +5874,65 @@ "ok": { "type": "boolean" }, - "content_type": { - "type": "string", - "example": "image/png" - }, "data": { - "type": "string", - "example": "iVBORw0KGgoAAAANSUhEUgAAE2AAAAVOCAIAAAA..." + "properties": { + "seat_summary": { + "$ref": "#/components/schemas/libcal_utilisation_seat_summary" + }, + "space_summary": { + "$ref": "#/components/schemas/libcal_utilisation_space_summary" + }, + "zones": { + "type": "array", + "items": { + "allOf": [ + { + "$ref": "#/components/schemas/libcal_zone" + } + ], + "properties": { + "spaces": { + "type": "array", + "items": { + "properties": { + "id": { + "$ref": "#/components/schemas/libcal_space_id" + }, + "name": { + "$ref": "#/components/schemas/libcal_space_name" + }, + "bookable_as_whole": { + "type": "boolean", + "description": "Whether the entire LibCal zone can be booked as a whole", + "example": false + }, + "current_occupancy": { + "type": "integer", + "description": "Number of persons within the zone", + "example": 15 + }, + "current_capacity": { + "type": "integer", + "description": "Maximum number of people allowed within the zone at this period in time", + "example": 20 + }, + "max_capacity": { + "type": "integer", + "description": "Maximum number of people allowed within the zone at any time", + "example": 50 + } + } + } + } + } + } + }, + "date": { + "type": "string", + "description": "Timestamp (in ISO 8601 format) at which this data was retrieved", + "example": "2021-06-27T12:00:01+01:00" + } + } } } } @@ -3682,23 +5968,14 @@ "7": { "$ref": "#/components/examples/ErrorInactiveToken" }, - "Missing image ID parameter": { - "value": { - "ok": false, - "error": "No Image ID provided." - } + "8": { + "$ref": "#/components/examples/ErrorPersonalData" }, - "Invalid image ID": { - "value": { - "ok": false, - "error": "The image with the ID you requested does not exist." - } + "9": { + "$ref": "#/components/examples/ErrorRejectedScope" }, - "Unsupported image format": { - "value": { - "ok": false, - "error": "You specified a response format that was not either raw or base64." - } + "10": { + "$ref": "#/components/examples/ErrorLibCalOAuthTokenInvalid" } } } @@ -3707,76 +5984,68 @@ } } }, - "/workspaces/images/map/live": { + "/libcal/space/seats": { "get": { - "summary": "Takes Survey ID and Map ID as parameters and displays a dynamically generated SVG map.", - "description": "The SVG map is correct as of the time of the API call (aside from caching overhead), showing the map's plan image with a circle overlaid on each seat. This circle is coloured based on whether the seat is occupied or absent (e.g. it's free).\n\nThere are also several parameters that let you customise the map to suit your app or integration.", + "summary": "Get all LibCal seats in a given location", "tags": [ - "Workspaces" - ], - "security": [ - { - "OAuthSecurity": [], - "OAuthToken": [] - } + "LibCal" ], "parameters": [ { - "$ref": "#/components/parameters/survey_id" + "$ref": "#/components/parameters/libcal_location_id" }, { - "name": "map_id", - "in": "query", - "description": "The ID of the library's survey which contains the map you want to obtain.", - "required": true, - "schema": { - "type": "number" - } + "$ref": "#/components/parameters/libcal_space_id" }, { - "name": "image_scale", - "in": "query", - "description": "The SVG image's scale. The default is 0.02. The scale is implemented as an SVG transform scale, and is applied to both the x and the y axes of the image.", - "required": false, - "schema": { - "type": "number" - } + "$ref": "#/components/parameters/libcal_category_id" }, { - "name": "circle_radius", + "name": "seat_id", "in": "query", - "description": "The size of the circle. This must be a positive float value. The default is 128.", + "description": "Show only the seat with this ID. If this is specified, spaceId, categoryId, and zoneId will be ignored.", "required": false, + "example": "54435", "schema": { - "type": "number" + "type": "string" } }, { - "name": "absent_colour", - "in": "query", - "description": "TThe colour of the circle designating a free seat. This must be provided as a hex colour code, including the preceeding", - "required": false, - "schema": { - "type": "number" - } + "$ref": "#/components/parameters/libcal_accessible_only" }, { - "name": "occupied_colour", - "in": "query", - "description": "The colour of the circle designating a taken, or occupied, seat. This must be provided as a hex colour code, including the preceeding", - "required": false, - "schema": { - "type": "number" - } + "$ref": "#/components/parameters/libcal_availability" + }, + { + "$ref": "#/components/parameters/libcal_page_index" + }, + { + "$ref": "#/components/parameters/libcal_page_size" + } + ], + "security": [ + { + "ApiToken": [] } ], "responses": { "200": { "description": "Success", "content": { - "application/xml": { + "application/json": { "schema": { - "$ref": "#/components/schemas/svg" + "type": "object", + "properties": { + "ok": { + "type": "boolean" + }, + "seats": { + "type": "array", + "items": { + "$ref": "#/components/schemas/libcal_seat" + } + } + } } } } @@ -3810,80 +6079,39 @@ "7": { "$ref": "#/components/examples/ErrorInactiveToken" }, - "Missing parameters": { - "value": { - "ok": false, - "error": "You must provide a Survey ID and a Map ID to get a live sensor status image." - } - }, - "Invalid colours": { - "value": { - "ok": false, - "error": "The custom colours you specified did not match the formal of HTML hex colours. Colours must either be in the format #ABC or #ABCDEF." - } - }, - "Invalid scale": { - "value": { - "ok": false, - "error": "The scale you specified is not valid. It must be a floating point number, such as 1 or 0.02." - } - }, - "Invalid circle radius": { - "value": { - "ok": false, - "error": "The circle radius you specified is not valid. It must be a floating point number, such as 128 or 100.5." - } + "8": { + "$ref": "#/components/examples/ErrorPersonalData" }, - "Invalid survey IDs": { - "value": { - "ok": false, - "error": "Either the IDs you sent were not integers, or they do not exist." - } - } - } - } - } - } - } - } - }, - "/workspaces/historical/data": { - "get": { - "summary": "List Historical Data", - "description": "This endpoint provides historical sensor readings for all sensors in all survey locations. This must be restricted to a single survey location with survey_id and can be optionally restricted to a single sensor with sensor_id.\n\nTo specify a start time datetime__gte (datetime greater than or equal to) and for an end time datetime__lte (datetime less than or equal to) can be used. The deltas (changes) of a sensor will be returned.\n\nConforms to CursorPagination from Django REST.\n\nThis endpoint will return a dictionary of every sensor reading in the time range.", - "tags": [ - "Workspaces" - ], - "parameters": [ - { - "$ref": "#/components/parameters/cursor" - }, - { - "$ref": "#/components/parameters/survey_id" - }, - { - "$ref": "#/components/parameters/sensor_id" - }, - { - "$ref": "#/components/parameters/datetime__gte" - }, - { - "$ref": "#/components/parameters/datetime__lte" - }, - { - "$ref": "#/components/parameters/datetime__exact" - }, + "9": { + "$ref": "#/components/examples/ErrorRejectedScope" + }, + "10": { + "$ref": "#/components/examples/ErrorLibCalOAuthTokenInvalid" + } + } + } + } + } + } + } + }, + "/libcal/space/seat": { + "get": { + "summary": "Get LibCal seat by ID", + "tags": [ + "LibCal" + ], + "parameters": [ { - "$ref": "#/components/parameters/datetime__gt" + "$ref": "#/components/parameters/libcal_category_ids" }, { - "$ref": "#/components/parameters/datetime__lt" + "$ref": "#/components/parameters/libcal_availability" } ], "security": [ { - "OAuthSecurity": [], - "OAuthToken": [] + "ApiToken": [] } ], "responses": { @@ -3897,24 +6125,8 @@ "ok": { "type": "boolean" }, - "data": { - "type": "object", - "properties": { - "next": { - "type": "string", - "example": null - }, - "previous": { - "type": "string", - "example": null - }, - "results": { - "type": "array", - "items": { - "$ref": "#/components/schemas/historical_survey_data" - } - } - } + "seat": { + "$ref": "#/components/schemas/libcal_seat" } } } @@ -3949,6 +6161,15 @@ }, "7": { "$ref": "#/components/examples/ErrorInactiveToken" + }, + "8": { + "$ref": "#/components/examples/ErrorPersonalData" + }, + "9": { + "$ref": "#/components/examples/ErrorRejectedScope" + }, + "10": { + "$ref": "#/components/examples/ErrorLibCalOAuthTokenInvalid" } } } @@ -3957,28 +6178,20 @@ } } }, - "/workspaces/historical/sensors": { + "/libcal/space/zones": { "get": { - "summary": "List Historical Sensors", - "description": "This endpoint lists all sensors in a survey location, this includes inactive sensors (unlike get sensors from workspaces).\n\nConforms to StandardResultsSetPagination from Django REST.\n\nThis endpoint will return a list of every sensor.", + "summary": "Get LibCal zones by location", "tags": [ - "Workspaces" + "LibCal" ], "parameters": [ { - "$ref": "#/components/parameters/page" - }, - { - "$ref": "#/components/parameters/survey_id" - }, - { - "$ref": "#/components/parameters/sensor_id" + "$ref": "#/components/parameters/libcal_location_id" } ], "security": [ { - "OAuthSecurity": [], - "OAuthToken": [] + "ApiToken": [] } ], "responses": { @@ -3992,25 +6205,20 @@ "ok": { "type": "boolean" }, - "data": { - "type": "object", - "properties": { - "next": { - "type": "string", - "example": "https://uclapi.com/workspaces/historical/sensors?page=2" - }, - "previous": { - "type": "string", - "example": null - }, - "count": { - "type": "integer", - "example": 17936 - }, - "results": { - "type": "array", - "items": { - "$ref": "#/components/schemas/historical_sensor" + "zones": { + "type": "array", + "items": { + "allOf": [ + { + "$ref": "#/components/schemas/libcal_zone" + } + ], + "properties": { + "item_ids": { + "type": "array", + "items": { + "$ref": "#/components/schemas/libcal_space_id" + } } } } @@ -4048,6 +6256,15 @@ }, "7": { "$ref": "#/components/examples/ErrorInactiveToken" + }, + "8": { + "$ref": "#/components/examples/ErrorPersonalData" + }, + "9": { + "$ref": "#/components/examples/ErrorRejectedScope" + }, + "10": { + "$ref": "#/components/examples/ErrorLibCalOAuthTokenInvalid" } } } @@ -4056,28 +6273,20 @@ } } }, - "/workspaces/historical/surveys": { + "/libcal/space/zone": { "get": { - "summary": "List Historical Surveys", - "description": "This endpoint lists all historical survey locations, this includes inactive survey locations (unlike get survey from workspaces).\n\nConforms to StandardResultsSetPagination from Django REST.", + "summary": "Get LibCal zone by ID", "tags": [ - "Workspaces" + "LibCal" ], "parameters": [ { - "$ref": "#/components/parameters/page" - }, - { - "$ref": "#/components/parameters/survey_id" - }, - { - "$ref": "#/components/parameters/active" + "$ref": "#/components/parameters/libcal_zone_id" } ], "security": [ { - "OAuthSecurity": [], - "OAuthToken": [] + "ApiToken": [] } ], "responses": { @@ -4089,27 +6298,25 @@ "type": "object", "properties": { "ok": { - "type": "boolean" + "type": "boolean", + "example": true }, - "surveys": { - "type": "object", + "error": { + "type": "string", + "description": "Will be returned if there is an error retrieving the given LibCal space, e.g. if the space ID provided is invalid", + "example": "Zone not found." + }, + "zone": { + "allOf": [ + { + "$ref": "#/components/schemas/libcal_zone" + } + ], "properties": { - "next": { - "type": "string", - "example": "https://uclapi.com/workspaces/historical/sensors?page=2" - }, - "previous": { - "type": "string", - "example": null - }, - "count": { - "type": "integer", - "example": 17936 - }, - "results": { + "item_ids": { "type": "array", "items": { - "$ref": "#/components/schemas/historical_survey" + "$ref": "#/components/schemas/libcal_space_id" } } } @@ -4147,6 +6354,15 @@ }, "7": { "$ref": "#/components/examples/ErrorInactiveToken" + }, + "8": { + "$ref": "#/components/examples/ErrorPersonalData" + }, + "9": { + "$ref": "#/components/examples/ErrorRejectedScope" + }, + "10": { + "$ref": "#/components/examples/ErrorLibCalOAuthTokenInvalid" } } } @@ -4155,16 +6371,87 @@ } } }, - "/dashboard/api/analytics/total": { + "/libcal/space/bookings": { "get": { - "summary": "Gets the total number of requests made from a given token", + "summary": "Get all LibCal bookings", "tags": [ - "Analytics" + "LibCal" + ], + "parameters": [ + { + "name": "eid", + "in": "query", + "description": "Comma delimited list of LibCal space IDs. If specified, will only show bookings for those spaces.", + "required": false, + "example": "469,470", + "schema": { + "type": "string" + } + }, + { + "name": "seat_id", + "in": "query", + "description": "Comma delimited list of LibCal seat IDs. If specified, will only show bookings for those seats.", + "required": false, + "example": "54435,54436", + "schema": { + "type": "string" + } + }, + { + "name": "cid", + "in": "query", + "description": "Comma delimited list of LibCal category IDs. If specified, will only show bookings for those categories.", + "required": false, + "example": "3334", + "schema": { + "type": "string" + } + }, + { + "name": "lid", + "in": "query", + "description": "Comma delimited list of LibCal location IDs. If specified, will only show bookings for those locations.", + "required": false, + "example": "702,703", + "schema": { + "type": "string" + } + }, + { + "name": "date", + "in": "query", + "description": "Date in YYYY-MM-DD format. If specified, will only show bookings made on this date. Dates in the past are ignored. Defaults to today's date.", + "required": false, + "example": "2021-06-01", + "schema": { + "type": "string" + } + }, + { + "name": "days", + "in": "query", + "description": "Number of days into the future to retrieve bookings from, starting from the data parameter. Defaults to zero. Must be >= 0 and <= 365.", + "required": false, + "example": 3, + "schema": { + "type": "integer" + } + }, + { + "name": "limit", + "in": "query", + "description": "Maximum number of bookings to return. Defaults to 20. The maximum value is 500.", + "required": false, + "example": 10, + "schema": { + "type": "integer" + } + } ], "security": [ { - "OAuthSecurity": [], - "OAuthToken": [] + "ApiToken": [] } ], "responses": { @@ -4176,10 +6463,14 @@ "type": "object", "properties": { "ok": { - "type": "boolean" + "type": "boolean", + "example": true }, - "num": { - "type": "number" + "bookings": { + "type": "array", + "items": { + "$ref": "#/components/schemas/libcal_seat_booking" + } } } } @@ -4205,23 +6496,138 @@ }, "4": { "$ref": "#/components/examples/ErrorThrottling" + }, + "5": { + "$ref": "#/components/examples/ErrorNoClientSecret" + }, + "6": { + "$ref": "#/components/examples/ErrorInvalidClientSecret" + }, + "7": { + "$ref": "#/components/examples/ErrorInactiveToken" + }, + "8": { + "$ref": "#/components/examples/ErrorPersonalData" + }, + "9": { + "$ref": "#/components/examples/ErrorRejectedScope" + }, + "10": { + "$ref": "#/components/examples/ErrorLibCalOAuthTokenInvalid" } } } } } - } - } - }, - "/dashboard/api/analytics/quota": { - "get": { - "summary": "Gets the remaining daily quota for a given token", - "tags": [ - "Analytics" + } + } + }, + "/libcal/space/personal_bookings": { + "get": { + "summary": "Get all LibCal bookings", + "tags": [ + "LibCal" + ], + "parameters": [ + { + "$ref": "#/components/parameters/client_secret" + }, + { + "name": "eid", + "in": "query", + "description": "Comma delimited list of LibCal space IDs. If specified, will only show bookings for those spaces.", + "required": false, + "example": "469,470", + "schema": { + "type": "string" + } + }, + { + "name": "seat_id", + "in": "query", + "description": "Comma delimited list of LibCal seat IDs. If specified, will only show bookings for those seats.", + "required": false, + "example": "54435,54436", + "schema": { + "type": "string" + } + }, + { + "name": "cid", + "in": "query", + "description": "Comma delimited list of LibCal category IDs. If specified, will only show bookings for those categories.", + "required": false, + "example": "3334", + "schema": { + "type": "string" + } + }, + { + "name": "lid", + "in": "query", + "description": "Comma delimited list of LibCal location IDs. If specified, will only show bookings for those locations.", + "required": false, + "example": "702,703", + "schema": { + "type": "string" + } + }, + { + "name": "email", + "in": "query", + "description": "If specified, will only show bookings made with this email address", + "required": false, + "example": "isd_apiteam@ucl.ac.uk", + "schema": { + "type": "string" + } + }, + { + "name": "date", + "in": "query", + "description": "Date in YYYY-MM-DD format. If specified, will only show bookings made on this date. Dates in the past are ignored. Defaults to today's date.", + "required": false, + "example": "2021-06-01", + "schema": { + "type": "string" + } + }, + { + "name": "days", + "in": "query", + "description": "Number of days into the future to retrieve bookings from, starting from the data parameter. Defaults to zero. Must be >= 0 and <= 365.", + "required": false, + "example": 3, + "schema": { + "type": "integer" + } + }, + { + "name": "limit", + "in": "query", + "description": "Maximum number of bookings to return. Defaults to 20. The maximum value is 500.", + "required": false, + "example": 10, + "schema": { + "type": "integer" + } + }, + { + "name": "form_answers", + "in": "query", + "description": "Whether or not form answers should be returned. Defaults to false.", + "required": false, + "example": true, + "schema": { + "type": "boolean" + } + } ], "security": [ { - "OAuthSecurity": [], + "OAuthSecurity": [ + "libcal_read" + ], "OAuthToken": [] } ], @@ -4234,10 +6640,14 @@ "type": "object", "properties": { "ok": { - "type": "boolean" + "type": "boolean", + "example": true }, - "remaining": { - "type": "number" + "bookings": { + "type": "array", + "items": { + "$ref": "#/components/schemas/libcal_personal_seat_booking" + } } } } @@ -4272,6 +6682,18 @@ }, "7": { "$ref": "#/components/examples/ErrorInactiveToken" + }, + "8": { + "$ref": "#/components/examples/ErrorPersonalData" + }, + "9": { + "$ref": "#/components/examples/ErrorRejectedScope" + }, + "10": { + "$ref": "#/components/examples/ErrorLibCalOAuthTokenInvalid" + }, + "11": { + "$ref": "#/components/examples/ErrorLibCalOAuth" } } } @@ -4280,63 +6702,31 @@ } } }, - "/dashboard/api/analytics/services": { - "get": { - "summary": "Gets all services and their popularity", + "/libcal/space/reserve": { + "post": { + "summary": "Reserve one or more LibCal spaces/seats", "tags": [ - "Analytics" + "LibCal" ], - "responses": { - "200": { - "description": "Success", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "ok": { - "type": "boolean" - }, - "data": { - "type": "array", - "items": { - "type": "object", - "properties": { - "service": { - "type": "string", - "example": "roombookings" - }, - "count": { - "type": "integer" - } - } - } - } - } - } - } - } + "parameters": [], + "security": [ + { + "OAuthSecurity": [ + "libcal_write" + ], + "OAuthToken": [] } - } - } - }, - "/dashboard/api/analytics/methods": { - "get": { - "summary": "Gets all methods for a given service and their popularity", - "tags": [ - "Analytics" ], - "parameters": [ - { - "name": "service", - "in": "query", - "description": "The service to check the popularity of methods for", - "required": false, - "schema": { - "type": "string" + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/libcal_reserve_request" + } } } - ], + }, "responses": { "200": { "description": "Success", @@ -4346,76 +6736,41 @@ "type": "object", "properties": { "ok": { - "type": "boolean" + "type": "boolean", + "example": true }, - "data": { - "type": "array", - "items": { - "type": "object", - "properties": { - "method": { + "error": { + "description": "Will only be returned if there are errors", + "properties": { + "errors": { + "type": "array", + "items": { "type": "string", - "example": "rooms" - }, - "count": { - "type": "integer" + "description": "error messages", + "example": "booking 0 'to' is not a valid ending slot" } } } - } - } - } - } - } - } - } - } - }, - "/dashboard/api/analytics/oauth/total": { - "get": { - "summary": "Gets the total number of users for a given app token", - "tags": [ - "Analytics" - ], - "security": [ - { - "OAuthSecurity": [], - "OAuthToken": [] - } - ], - "parameters": [ - { - "name": "start_date", - "in": "query", - "description": "Start date to filter by", - "required": false, - "schema": { - "type": "string" - } - }, - { - "name": "end_date", - "in": "query", - "description": "End date to filter by", - "required": false, - "schema": { - "type": "string" - } - } - ], - "responses": { - "200": { - "description": "Success", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "ok": { - "type": "boolean" }, - "users": { - "type": "integer" + "bookings": { + "properties": { + "success": { + "type": "string", + "description": "Returns only if the test flag was supplied and the booking was successfully placed", + "example": "this booking would have been successfully placed, but you supplied the test flag." + }, + "booking_id": { + "$ref": "#/components/schemas/libcal_booking_id" + }, + "cost": { + "type": "string", + "description": "The cost of the LibCal booking. Should generally be 0.", + "example": "0" + } + }, + "required": [ + "booking_id" + ] } } } @@ -4432,6 +6787,36 @@ "examples": { "1": { "$ref": "#/components/examples/ErrorNoToken" + }, + "2": { + "$ref": "#/components/examples/ErrorTokenNotExist" + }, + "3": { + "$ref": "#/components/examples/ErrorInvalidToken" + }, + "4": { + "$ref": "#/components/examples/ErrorThrottling" + }, + "5": { + "$ref": "#/components/examples/ErrorNoClientSecret" + }, + "6": { + "$ref": "#/components/examples/ErrorInvalidClientSecret" + }, + "7": { + "$ref": "#/components/examples/ErrorInactiveToken" + }, + "8": { + "$ref": "#/components/examples/ErrorPersonalData" + }, + "9": { + "$ref": "#/components/examples/ErrorRejectedScope" + }, + "10": { + "$ref": "#/components/examples/ErrorLibCalOAuthTokenInvalid" + }, + "11": { + "$ref": "#/components/examples/ErrorLibCalOAuth" } } } @@ -4440,15 +6825,22 @@ } } }, - "/dashboard/api/analytics/oauth/total_by_dept": { - "get": { - "summary": "Gets the total number of users for a given app token, by department", + "/libcal/space/cancel": { + "post": { + "summary": "Cancel one or more LibCal bookings", "tags": [ - "Analytics" + "LibCal" + ], + "parameters": [ + { + "$ref": "#/components/parameters/libcal_booking_ids" + } ], "security": [ { - "OAuthSecurity": [], + "OAuthSecurity": [ + "libcal_write" + ], "OAuthToken": [] } ], @@ -4461,19 +6853,20 @@ "type": "object", "properties": { "ok": { - "type": "boolean" + "type": "boolean", + "example": true }, - "data": { + "bookings": { "type": "array", "items": { - "type": "object", "properties": { - "department": { - "type": "string", - "example": "Dept of Computer Science" + "booking_id": { + "$ref": "#/components/schemas/libcal_booking_id" }, - "count": { - "type": "integer" + "cancelled": { + "type": "boolean", + "description": "Whether the LibCal booking was successfully cancelled", + "example": true } } } @@ -4493,6 +6886,39 @@ "examples": { "1": { "$ref": "#/components/examples/ErrorNoToken" + }, + "2": { + "$ref": "#/components/examples/ErrorTokenNotExist" + }, + "3": { + "$ref": "#/components/examples/ErrorInvalidToken" + }, + "4": { + "$ref": "#/components/examples/ErrorThrottling" + }, + "5": { + "$ref": "#/components/examples/ErrorNoClientSecret" + }, + "6": { + "$ref": "#/components/examples/ErrorInvalidClientSecret" + }, + "7": { + "$ref": "#/components/examples/ErrorInactiveToken" + }, + "8": { + "$ref": "#/components/examples/ErrorPersonalData" + }, + "9": { + "$ref": "#/components/examples/ErrorRejectedScope" + }, + "10": { + "$ref": "#/components/examples/ErrorLibCalOAuthTokenInvalid" + }, + "11": { + "$ref": "#/components/examples/ErrorLibCalOAuth" + }, + "12": { + "$ref": "#/components/examples/ErrorLibCalNoBookingsDeleted" } } }