diff --git a/README.md b/README.md index 9d6bfce..bc51bc5 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.4.9 -- Package version: 1.4.9 +- API version: 1.4.10 +- Package version: 1.4.10 - Build package: org.openapitools.codegen.languages.JavascriptClientCodegen ## Installation diff --git a/openapitools.json b/openapitools.json index f5c6613..8072f4e 100644 --- a/openapitools.json +++ b/openapitools.json @@ -11,7 +11,7 @@ "templateDir": "#{cwd}/sdk-templates", "additionalProperties": { "projectName": "@uclapi/sdk", - "projectVersion": "1.4.9", + "projectVersion": "1.4.10", "moduleName": "uclapi", "projectDescription": "UCL API JavaScript SDK" } diff --git a/package.json b/package.json index e6d0a69..5c7e4a7 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@uclapi/sdk", - "version": "1.4.9", + "version": "1.4.10", "description": "UCL API JavaScript SDK", "license": "MIT License", "main": "dist/index.js", diff --git a/src/ApiClient.js b/src/ApiClient.js index c340b0e..e6dd57c 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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.4.9 +* @version 1.4.10 */ /** diff --git a/src/api/AnalyticsApi.js b/src/api/AnalyticsApi.js index 9043aae..d45d5ca 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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.4.9 +* @version 1.4.10 */ export default class AnalyticsApi { diff --git a/src/api/LibCalApi.js b/src/api/LibCalApi.js index b703fc7..f711a21 100644 --- a/src/api/LibCalApi.js +++ b/src/api/LibCalApi.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.4.9 + * The version of the OpenAPI document: 1.4.10 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -35,7 +35,7 @@ import LibcalReserveRequest from '../model/LibcalReserveRequest'; /** * LibCal service. * @module api/LibCalApi -* @version 1.4.9 +* @version 1.4.10 */ export default class LibCalApi { diff --git a/src/api/OAuthApi.js b/src/api/OAuthApi.js index 8733946..256767d 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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.4.9 +* @version 1.4.10 */ export default class OAuthApi { diff --git a/src/api/ResourcesApi.js b/src/api/ResourcesApi.js index cb9aaf0..03b43d1 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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.4.9 +* @version 1.4.10 */ export default class ResourcesApi { diff --git a/src/api/RoomBookingsApi.js b/src/api/RoomBookingsApi.js index 4b0ab2c..481e1df 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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.4.9 +* @version 1.4.10 */ export default class RoomBookingsApi { diff --git a/src/api/SearchApi.js b/src/api/SearchApi.js index f34098b..1d44ebb 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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.4.9 +* @version 1.4.10 */ export default class SearchApi { diff --git a/src/api/TimetableApi.js b/src/api/TimetableApi.js index 4b7c454..3fe3df9 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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.4.9 +* @version 1.4.10 */ export default class TimetableApi { diff --git a/src/api/WorkspacesApi.js b/src/api/WorkspacesApi.js index 63c26f7..d1b7260 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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.4.9 +* @version 1.4.10 */ export default class WorkspacesApi { diff --git a/src/index.js b/src/index.js index 62a1c70..7c513a8 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.4.9 + * The version of the OpenAPI document: 1.4.10 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -159,7 +159,7 @@ import WorkspacesApi from './api/WorkspacesApi'; * *

* @module index -* @version 1.4.9 +* @version 1.4.10 */ export { /** diff --git a/src/model/Average.js b/src/model/Average.js index e5490dd..23d34da 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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.4.9 + * @version 1.4.10 */ class Average { /** diff --git a/src/model/AverageWithNameAndId.js b/src/model/AverageWithNameAndId.js index 313b43c..6e72bd1 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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.4.9 + * @version 1.4.10 */ class AverageWithNameAndId { /** diff --git a/src/model/Booking.js b/src/model/Booking.js index 9ee14f4..22d18ca 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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.4.9 + * @version 1.4.10 */ class Booking { /** diff --git a/src/model/Course.js b/src/model/Course.js index 2f6c1f3..28a880f 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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.4.9 + * @version 1.4.10 */ class Course { /** diff --git a/src/model/Delivery.js b/src/model/Delivery.js index 1188784..1200e24 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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.4.9 + * @version 1.4.10 */ class Delivery { /** diff --git a/src/model/Department.js b/src/model/Department.js index f14e50f..122afab 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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.4.9 + * @version 1.4.10 */ class Department { /** diff --git a/src/model/DesktopData.js b/src/model/DesktopData.js index 673fdb7..656e18f 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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.4.9 + * @version 1.4.10 */ class DesktopData { /** diff --git a/src/model/DesktopDataLocation.js b/src/model/DesktopDataLocation.js index 763497b..edebf31 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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.4.9 + * @version 1.4.10 */ class DesktopDataLocation { /** diff --git a/src/model/Equipment.js b/src/model/Equipment.js index 5504940..40fd7c0 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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.4.9 + * @version 1.4.10 */ class Equipment { /** diff --git a/src/model/Error.js b/src/model/Error.js index ac061f5..b46d718 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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.4.9 + * @version 1.4.10 */ class Error { /** diff --git a/src/model/Event.js b/src/model/Event.js index 47419c3..cdcb8ac 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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.4.9 + * @version 1.4.10 */ class Event { /** diff --git a/src/model/HistoricalSensor.js b/src/model/HistoricalSensor.js index 48563c3..96a129d 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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.4.9 + * @version 1.4.10 */ class HistoricalSensor { /** diff --git a/src/model/HistoricalSurvey.js b/src/model/HistoricalSurvey.js index f840934..500a7b1 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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.4.9 + * @version 1.4.10 */ class HistoricalSurvey { /** diff --git a/src/model/HistoricalSurveyData.js b/src/model/HistoricalSurveyData.js index 7b4ca3d..8e46b9d 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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.4.9 + * @version 1.4.10 */ class HistoricalSurveyData { /** diff --git a/src/model/InlineResponse200.js b/src/model/InlineResponse200.js index e053edb..77a514e 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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.4.9 + * @version 1.4.10 */ class InlineResponse200 { /** diff --git a/src/model/InlineResponse2001.js b/src/model/InlineResponse2001.js index 3b57075..9e5a6bc 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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.4.9 + * @version 1.4.10 */ class InlineResponse2001 { /** diff --git a/src/model/InlineResponse20010.js b/src/model/InlineResponse20010.js index 019476d..184e1d6 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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.4.9 + * @version 1.4.10 */ class InlineResponse20010 { /** diff --git a/src/model/InlineResponse20011.js b/src/model/InlineResponse20011.js index 02f41ab..b31c5d6 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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.4.9 + * @version 1.4.10 */ class InlineResponse20011 { /** diff --git a/src/model/InlineResponse20012.js b/src/model/InlineResponse20012.js index 049c7e7..8e61138 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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.4.9 + * @version 1.4.10 */ class InlineResponse20012 { /** diff --git a/src/model/InlineResponse20013.js b/src/model/InlineResponse20013.js index c762582..c03464b 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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.4.9 + * @version 1.4.10 */ class InlineResponse20013 { /** diff --git a/src/model/InlineResponse20014.js b/src/model/InlineResponse20014.js index a3a296c..67557c0 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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.4.9 + * @version 1.4.10 */ class InlineResponse20014 { /** diff --git a/src/model/InlineResponse20015.js b/src/model/InlineResponse20015.js index 4660983..fb8bec2 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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.4.9 + * @version 1.4.10 */ class InlineResponse20015 { /** diff --git a/src/model/InlineResponse20016.js b/src/model/InlineResponse20016.js index cb86ba3..aa6c1e5 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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.4.9 + * @version 1.4.10 */ class InlineResponse20016 { /** diff --git a/src/model/InlineResponse20017.js b/src/model/InlineResponse20017.js index 92409c9..c337634 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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.4.9 + * @version 1.4.10 */ class InlineResponse20017 { /** diff --git a/src/model/InlineResponse20018.js b/src/model/InlineResponse20018.js index 0ec4e9c..ae8a099 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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.4.9 + * @version 1.4.10 */ class InlineResponse20018 { /** diff --git a/src/model/InlineResponse20018Data.js b/src/model/InlineResponse20018Data.js index 9a9d60f..b81572a 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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.4.9 + * @version 1.4.10 */ class InlineResponse20018Data { /** diff --git a/src/model/InlineResponse20019.js b/src/model/InlineResponse20019.js index 4f46f85..f44c1bd 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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.4.9 + * @version 1.4.10 */ class InlineResponse20019 { /** diff --git a/src/model/InlineResponse20019Data.js b/src/model/InlineResponse20019Data.js index bd913f9..a068153 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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.4.9 + * @version 1.4.10 */ class InlineResponse20019Data { /** diff --git a/src/model/InlineResponse2002.js b/src/model/InlineResponse2002.js index a27fafb..16f65c5 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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.4.9 + * @version 1.4.10 */ class InlineResponse2002 { /** diff --git a/src/model/InlineResponse20020.js b/src/model/InlineResponse20020.js index 1ccaabe..e20581f 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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.4.9 + * @version 1.4.10 */ class InlineResponse20020 { /** diff --git a/src/model/InlineResponse20020Surveys.js b/src/model/InlineResponse20020Surveys.js index c495fab..57d0923 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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.4.9 + * @version 1.4.10 */ class InlineResponse20020Surveys { /** diff --git a/src/model/InlineResponse20021.js b/src/model/InlineResponse20021.js index 5875f7b..efbe557 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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.4.9 + * @version 1.4.10 */ class InlineResponse20021 { /** diff --git a/src/model/InlineResponse20022.js b/src/model/InlineResponse20022.js index 72e29e3..8272f71 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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.4.9 + * @version 1.4.10 */ class InlineResponse20022 { /** diff --git a/src/model/InlineResponse20023.js b/src/model/InlineResponse20023.js index ce2d596..57c6036 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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.4.9 + * @version 1.4.10 */ class InlineResponse20023 { /** diff --git a/src/model/InlineResponse20023Data.js b/src/model/InlineResponse20023Data.js index fbc5343..c8721c4 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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.4.9 + * @version 1.4.10 */ class InlineResponse20023Data { /** diff --git a/src/model/InlineResponse20024.js b/src/model/InlineResponse20024.js index a046366..8253b67 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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.4.9 + * @version 1.4.10 */ class InlineResponse20024 { /** diff --git a/src/model/InlineResponse20024Data.js b/src/model/InlineResponse20024Data.js index fddaa08..2808edd 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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.4.9 + * @version 1.4.10 */ class InlineResponse20024Data { /** diff --git a/src/model/InlineResponse20025.js b/src/model/InlineResponse20025.js index 98488d9..db57a3f 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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.4.9 + * @version 1.4.10 */ class InlineResponse20025 { /** diff --git a/src/model/InlineResponse20026.js b/src/model/InlineResponse20026.js index 72f752e..b8e28c7 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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.4.9 + * @version 1.4.10 */ class InlineResponse20026 { /** diff --git a/src/model/InlineResponse20026Data.js b/src/model/InlineResponse20026Data.js index c29af3f..70e0372 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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.4.9 + * @version 1.4.10 */ class InlineResponse20026Data { /** diff --git a/src/model/InlineResponse20027.js b/src/model/InlineResponse20027.js index 0cc886c..ea99af2 100644 --- a/src/model/InlineResponse20027.js +++ b/src/model/InlineResponse20027.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.4.9 + * The version of the OpenAPI document: 1.4.10 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -17,7 +17,7 @@ import LibcalLocation from './LibcalLocation'; /** * The InlineResponse20027 model module. * @module model/InlineResponse20027 - * @version 1.4.9 + * @version 1.4.10 */ class InlineResponse20027 { /** diff --git a/src/model/InlineResponse20028.js b/src/model/InlineResponse20028.js index 70f1ead..35a77c2 100644 --- a/src/model/InlineResponse20028.js +++ b/src/model/InlineResponse20028.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.4.9 + * The version of the OpenAPI document: 1.4.10 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -17,7 +17,7 @@ import LibcalLocationBase from './LibcalLocationBase'; /** * The InlineResponse20028 model module. * @module model/InlineResponse20028 - * @version 1.4.9 + * @version 1.4.10 */ class InlineResponse20028 { /** diff --git a/src/model/InlineResponse20029.js b/src/model/InlineResponse20029.js index 553bb38..51afd7b 100644 --- a/src/model/InlineResponse20029.js +++ b/src/model/InlineResponse20029.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.4.9 + * The version of the OpenAPI document: 1.4.10 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -17,7 +17,7 @@ import InlineResponse20029Categories from './InlineResponse20029Categories'; /** * The InlineResponse20029 model module. * @module model/InlineResponse20029 - * @version 1.4.9 + * @version 1.4.10 */ class InlineResponse20029 { /** diff --git a/src/model/InlineResponse20029Categories.js b/src/model/InlineResponse20029Categories.js index b51ad05..472ec6c 100644 --- a/src/model/InlineResponse20029Categories.js +++ b/src/model/InlineResponse20029Categories.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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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 InlineResponse20029Categories model module. * @module model/InlineResponse20029Categories - * @version 1.4.9 + * @version 1.4.10 */ class InlineResponse20029Categories { /** diff --git a/src/model/InlineResponse2003.js b/src/model/InlineResponse2003.js index 7a7a5b7..06b1407 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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.4.9 + * @version 1.4.10 */ class InlineResponse2003 { /** diff --git a/src/model/InlineResponse20030.js b/src/model/InlineResponse20030.js index 4b01e0a..2240c7f 100644 --- a/src/model/InlineResponse20030.js +++ b/src/model/InlineResponse20030.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.4.9 + * The version of the OpenAPI document: 1.4.10 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -17,7 +17,7 @@ import LibcalForm from './LibcalForm'; /** * The InlineResponse20030 model module. * @module model/InlineResponse20030 - * @version 1.4.9 + * @version 1.4.10 */ class InlineResponse20030 { /** diff --git a/src/model/InlineResponse20031.js b/src/model/InlineResponse20031.js index 2ea5ef9..c3a5529 100644 --- a/src/model/InlineResponse20031.js +++ b/src/model/InlineResponse20031.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.4.9 + * The version of the OpenAPI document: 1.4.10 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -17,7 +17,7 @@ import LibcalFormField from './LibcalFormField'; /** * The InlineResponse20031 model module. * @module model/InlineResponse20031 - * @version 1.4.9 + * @version 1.4.10 */ class InlineResponse20031 { /** diff --git a/src/model/InlineResponse20032.js b/src/model/InlineResponse20032.js index fb3e480..be5af44 100644 --- a/src/model/InlineResponse20032.js +++ b/src/model/InlineResponse20032.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.4.9 + * The version of the OpenAPI document: 1.4.10 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -17,7 +17,7 @@ import LibcalSpaceBase from './LibcalSpaceBase'; /** * The InlineResponse20032 model module. * @module model/InlineResponse20032 - * @version 1.4.9 + * @version 1.4.10 */ class InlineResponse20032 { /** diff --git a/src/model/InlineResponse20033.js b/src/model/InlineResponse20033.js index 8278aa7..4a97e18 100644 --- a/src/model/InlineResponse20033.js +++ b/src/model/InlineResponse20033.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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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 InlineResponse20033 model module. * @module model/InlineResponse20033 - * @version 1.4.9 + * @version 1.4.10 */ class InlineResponse20033 { /** diff --git a/src/model/InlineResponse20034.js b/src/model/InlineResponse20034.js index 5e7dd43..328ca04 100644 --- a/src/model/InlineResponse20034.js +++ b/src/model/InlineResponse20034.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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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 InlineResponse20034 model module. * @module model/InlineResponse20034 - * @version 1.4.9 + * @version 1.4.10 */ class InlineResponse20034 { /** diff --git a/src/model/InlineResponse20035.js b/src/model/InlineResponse20035.js index 59a0268..b619188 100644 --- a/src/model/InlineResponse20035.js +++ b/src/model/InlineResponse20035.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.4.9 + * The version of the OpenAPI document: 1.4.10 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -17,7 +17,7 @@ import LibcalSeat from './LibcalSeat'; /** * The InlineResponse20035 model module. * @module model/InlineResponse20035 - * @version 1.4.9 + * @version 1.4.10 */ class InlineResponse20035 { /** diff --git a/src/model/InlineResponse20036.js b/src/model/InlineResponse20036.js index 99a9f15..25486d4 100644 --- a/src/model/InlineResponse20036.js +++ b/src/model/InlineResponse20036.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.4.9 + * The version of the OpenAPI document: 1.4.10 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -17,7 +17,7 @@ import LibcalSeat from './LibcalSeat'; /** * The InlineResponse20036 model module. * @module model/InlineResponse20036 - * @version 1.4.9 + * @version 1.4.10 */ class InlineResponse20036 { /** diff --git a/src/model/InlineResponse20037.js b/src/model/InlineResponse20037.js index 23d83cc..56ae8e7 100644 --- a/src/model/InlineResponse20037.js +++ b/src/model/InlineResponse20037.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.4.9 + * The version of the OpenAPI document: 1.4.10 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -17,7 +17,7 @@ import LibcalZone from './LibcalZone'; /** * The InlineResponse20037 model module. * @module model/InlineResponse20037 - * @version 1.4.9 + * @version 1.4.10 */ class InlineResponse20037 { /** diff --git a/src/model/InlineResponse20038.js b/src/model/InlineResponse20038.js index 5f6fcd4..eecf93b 100644 --- a/src/model/InlineResponse20038.js +++ b/src/model/InlineResponse20038.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.4.9 + * The version of the OpenAPI document: 1.4.10 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -17,7 +17,7 @@ import LibcalZone from './LibcalZone'; /** * The InlineResponse20038 model module. * @module model/InlineResponse20038 - * @version 1.4.9 + * @version 1.4.10 */ class InlineResponse20038 { /** diff --git a/src/model/InlineResponse20039.js b/src/model/InlineResponse20039.js index 760a562..f4d510e 100644 --- a/src/model/InlineResponse20039.js +++ b/src/model/InlineResponse20039.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.4.9 + * The version of the OpenAPI document: 1.4.10 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -17,7 +17,7 @@ import LibcalSeatBooking from './LibcalSeatBooking'; /** * The InlineResponse20039 model module. * @module model/InlineResponse20039 - * @version 1.4.9 + * @version 1.4.10 */ class InlineResponse20039 { /** diff --git a/src/model/InlineResponse2004.js b/src/model/InlineResponse2004.js index 14f9bed..c4a9ff9 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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.4.9 + * @version 1.4.10 */ class InlineResponse2004 { /** diff --git a/src/model/InlineResponse20040.js b/src/model/InlineResponse20040.js index 3716287..f1d6063 100644 --- a/src/model/InlineResponse20040.js +++ b/src/model/InlineResponse20040.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.4.9 + * The version of the OpenAPI document: 1.4.10 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -17,7 +17,7 @@ import LibcalPersonalSeatBooking from './LibcalPersonalSeatBooking'; /** * The InlineResponse20040 model module. * @module model/InlineResponse20040 - * @version 1.4.9 + * @version 1.4.10 */ class InlineResponse20040 { /** diff --git a/src/model/InlineResponse20041.js b/src/model/InlineResponse20041.js index 97977e6..0edcfc1 100644 --- a/src/model/InlineResponse20041.js +++ b/src/model/InlineResponse20041.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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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 InlineResponse20041 model module. * @module model/InlineResponse20041 - * @version 1.4.9 + * @version 1.4.10 */ class InlineResponse20041 { /** diff --git a/src/model/InlineResponse20042.js b/src/model/InlineResponse20042.js index 30ffaaf..657e55c 100644 --- a/src/model/InlineResponse20042.js +++ b/src/model/InlineResponse20042.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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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 InlineResponse20042 model module. * @module model/InlineResponse20042 - * @version 1.4.9 + * @version 1.4.10 */ class InlineResponse20042 { /** diff --git a/src/model/InlineResponse2005.js b/src/model/InlineResponse2005.js index 996f297..b391548 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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.4.9 + * @version 1.4.10 */ class InlineResponse2005 { /** diff --git a/src/model/InlineResponse2006.js b/src/model/InlineResponse2006.js index 5a62d7a..3f522a0 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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.4.9 + * @version 1.4.10 */ class InlineResponse2006 { /** diff --git a/src/model/InlineResponse2007.js b/src/model/InlineResponse2007.js index ece4760..224e19a 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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.4.9 + * @version 1.4.10 */ class InlineResponse2007 { /** diff --git a/src/model/InlineResponse2008.js b/src/model/InlineResponse2008.js index 1fb5f88..5ceb0fa 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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.4.9 + * @version 1.4.10 */ class InlineResponse2008 { /** diff --git a/src/model/InlineResponse2009.js b/src/model/InlineResponse2009.js index 3e30d40..4b8c0ec 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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.4.9 + * @version 1.4.10 */ class InlineResponse2009 { /** diff --git a/src/model/Instance.js b/src/model/Instance.js index 20c15f6..f1f7302 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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.4.9 + * @version 1.4.10 */ class Instance { /** diff --git a/src/model/Lecturer.js b/src/model/Lecturer.js index f0719a7..758aded 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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.4.9 + * @version 1.4.10 */ class Lecturer { /** diff --git a/src/model/LibcalBooking.js b/src/model/LibcalBooking.js index 86d1fb4..29c174d 100644 --- a/src/model/LibcalBooking.js +++ b/src/model/LibcalBooking.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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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 LibcalBooking model module. * @module model/LibcalBooking - * @version 1.4.9 + * @version 1.4.10 */ class LibcalBooking { /** diff --git a/src/model/LibcalCategory.js b/src/model/LibcalCategory.js index bae513c..fdbc117 100644 --- a/src/model/LibcalCategory.js +++ b/src/model/LibcalCategory.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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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 LibcalCategory model module. * @module model/LibcalCategory - * @version 1.4.9 + * @version 1.4.10 */ class LibcalCategory { /** diff --git a/src/model/LibcalForm.js b/src/model/LibcalForm.js index 0409427..85746fd 100644 --- a/src/model/LibcalForm.js +++ b/src/model/LibcalForm.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.4.9 + * The version of the OpenAPI document: 1.4.10 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -17,7 +17,7 @@ import LibcalFormField from './LibcalFormField'; /** * The LibcalForm model module. * @module model/LibcalForm - * @version 1.4.9 + * @version 1.4.10 */ class LibcalForm { /** diff --git a/src/model/LibcalFormField.js b/src/model/LibcalFormField.js index e3e57ce..260ff89 100644 --- a/src/model/LibcalFormField.js +++ b/src/model/LibcalFormField.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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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 LibcalFormField model module. * @module model/LibcalFormField - * @version 1.4.9 + * @version 1.4.10 */ class LibcalFormField { /** diff --git a/src/model/LibcalLocation.js b/src/model/LibcalLocation.js index db63236..00014be 100644 --- a/src/model/LibcalLocation.js +++ b/src/model/LibcalLocation.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.4.9 + * The version of the OpenAPI document: 1.4.10 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -17,7 +17,7 @@ import LibcalLocationBase from './LibcalLocationBase'; /** * The LibcalLocation model module. * @module model/LibcalLocation - * @version 1.4.9 + * @version 1.4.10 */ class LibcalLocation { /** diff --git a/src/model/LibcalLocationBase.js b/src/model/LibcalLocationBase.js index 7185d8c..4e2bb16 100644 --- a/src/model/LibcalLocationBase.js +++ b/src/model/LibcalLocationBase.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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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 LibcalLocationBase model module. * @module model/LibcalLocationBase - * @version 1.4.9 + * @version 1.4.10 */ class LibcalLocationBase { /** diff --git a/src/model/LibcalPersonalSeatBooking.js b/src/model/LibcalPersonalSeatBooking.js index 5ae4d35..7cf0e6d 100644 --- a/src/model/LibcalPersonalSeatBooking.js +++ b/src/model/LibcalPersonalSeatBooking.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.4.9 + * The version of the OpenAPI document: 1.4.10 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -17,7 +17,7 @@ import LibcalSeatBooking from './LibcalSeatBooking'; /** * The LibcalPersonalSeatBooking model module. * @module model/LibcalPersonalSeatBooking - * @version 1.4.9 + * @version 1.4.10 */ class LibcalPersonalSeatBooking { /** diff --git a/src/model/LibcalReserveRequest.js b/src/model/LibcalReserveRequest.js index 0ab5a93..cab1ec8 100644 --- a/src/model/LibcalReserveRequest.js +++ b/src/model/LibcalReserveRequest.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.4.9 + * The version of the OpenAPI document: 1.4.10 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -17,7 +17,7 @@ import LibcalReserveRequestBooking from './LibcalReserveRequestBooking'; /** * The LibcalReserveRequest model module. * @module model/LibcalReserveRequest - * @version 1.4.9 + * @version 1.4.10 */ class LibcalReserveRequest { /** diff --git a/src/model/LibcalReserveRequestBooking.js b/src/model/LibcalReserveRequestBooking.js index 56ace9c..2ee41b5 100644 --- a/src/model/LibcalReserveRequestBooking.js +++ b/src/model/LibcalReserveRequestBooking.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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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 LibcalReserveRequestBooking model module. * @module model/LibcalReserveRequestBooking - * @version 1.4.9 + * @version 1.4.10 */ class LibcalReserveRequestBooking { /** diff --git a/src/model/LibcalSeat.js b/src/model/LibcalSeat.js index 7d7dc36..0142dbb 100644 --- a/src/model/LibcalSeat.js +++ b/src/model/LibcalSeat.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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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 LibcalSeat model module. * @module model/LibcalSeat - * @version 1.4.9 + * @version 1.4.10 */ class LibcalSeat { /** diff --git a/src/model/LibcalSeatBooking.js b/src/model/LibcalSeatBooking.js index 8e12ec3..ccec62c 100644 --- a/src/model/LibcalSeatBooking.js +++ b/src/model/LibcalSeatBooking.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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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 LibcalSeatBooking model module. * @module model/LibcalSeatBooking - * @version 1.4.9 + * @version 1.4.10 */ class LibcalSeatBooking { /** diff --git a/src/model/LibcalSpaceBase.js b/src/model/LibcalSpaceBase.js index 0361961..5eb2c03 100644 --- a/src/model/LibcalSpaceBase.js +++ b/src/model/LibcalSpaceBase.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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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 LibcalSpaceBase model module. * @module model/LibcalSpaceBase - * @version 1.4.9 + * @version 1.4.10 */ class LibcalSpaceBase { /** diff --git a/src/model/LibcalUtilisationSeatSummary.js b/src/model/LibcalUtilisationSeatSummary.js index 0752995..f130dde 100644 --- a/src/model/LibcalUtilisationSeatSummary.js +++ b/src/model/LibcalUtilisationSeatSummary.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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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 LibcalUtilisationSeatSummary model module. * @module model/LibcalUtilisationSeatSummary - * @version 1.4.9 + * @version 1.4.10 */ class LibcalUtilisationSeatSummary { /** diff --git a/src/model/LibcalUtilisationSpaceSummary.js b/src/model/LibcalUtilisationSpaceSummary.js index 261e486..04d8206 100644 --- a/src/model/LibcalUtilisationSpaceSummary.js +++ b/src/model/LibcalUtilisationSpaceSummary.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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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 LibcalUtilisationSpaceSummary model module. * @module model/LibcalUtilisationSpaceSummary - * @version 1.4.9 + * @version 1.4.10 */ class LibcalUtilisationSpaceSummary { /** diff --git a/src/model/LibcalZone.js b/src/model/LibcalZone.js index 808a9dd..2c19f58 100644 --- a/src/model/LibcalZone.js +++ b/src/model/LibcalZone.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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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 LibcalZone model module. * @module model/LibcalZone - * @version 1.4.9 + * @version 1.4.10 */ class LibcalZone { /** diff --git a/src/model/Location.js b/src/model/Location.js index 9d1eca6..2dd1a84 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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.4.9 + * @version 1.4.10 */ class Location { /** diff --git a/src/model/LocationCoordinates.js b/src/model/LocationCoordinates.js index 2d48479..7bc6b61 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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.4.9 + * @version 1.4.10 */ class LocationCoordinates { /** diff --git a/src/model/Map.js b/src/model/Map.js index 6b7be24..55712ae 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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.4.9 + * @version 1.4.10 */ class Map { /** diff --git a/src/model/MapWithSensors.js b/src/model/MapWithSensors.js index 97a4103..bba8dc9 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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.4.9 + * @version 1.4.10 */ class MapWithSensors { /** diff --git a/src/model/Module.js b/src/model/Module.js index 1f8158b..8668650 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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.4.9 + * @version 1.4.10 */ class Module { /** diff --git a/src/model/ModuleDataCoursesModules.js b/src/model/ModuleDataCoursesModules.js index 6a32881..5145c51 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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.4.9 + * @version 1.4.10 */ class ModuleDataCoursesModules { /** diff --git a/src/model/Period.js b/src/model/Period.js index 0ba0df6..e2c2b50 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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.4.9 + * @version 1.4.10 */ class Period { /** diff --git a/src/model/Person.js b/src/model/Person.js index d2e03a3..e10eaf2 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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.4.9 + * @version 1.4.10 */ class Person { /** diff --git a/src/model/Room.js b/src/model/Room.js index d67e6cf..06d6407 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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.4.9 + * @version 1.4.10 */ class Room { /** diff --git a/src/model/RoomLocation.js b/src/model/RoomLocation.js index fb9ee06..35efe9b 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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.4.9 + * @version 1.4.10 */ class RoomLocation { /** diff --git a/src/model/SeatImage.js b/src/model/SeatImage.js index 8ca86e0..237a287 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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.4.9 + * @version 1.4.10 */ class SeatImage { /** diff --git a/src/model/SeatImageCircle.js b/src/model/SeatImageCircle.js index 58dffee..de39e3b 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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.4.9 + * @version 1.4.10 */ class SeatImageCircle { /** diff --git a/src/model/Sensor.js b/src/model/Sensor.js index 0a470b7..2fda9a4 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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.4.9 + * @version 1.4.10 */ class Sensor { /** diff --git a/src/model/SensorAverageSurvey.js b/src/model/SensorAverageSurvey.js index 9207cc1..9e95de0 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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.4.9 + * @version 1.4.10 */ class SensorAverageSurvey { /** diff --git a/src/model/SummerSchool.js b/src/model/SummerSchool.js index a08c76a..241bf3e 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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.4.9 + * @version 1.4.10 */ class SummerSchool { /** diff --git a/src/model/SummerSchoolSessions.js b/src/model/SummerSchoolSessions.js index 6bbd39a..035f958 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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.4.9 + * @version 1.4.10 */ class SummerSchoolSessions { /** diff --git a/src/model/Survey.js b/src/model/Survey.js index 1a93873..24373fc 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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.4.9 + * @version 1.4.10 */ class Survey { /** diff --git a/src/model/SurveyLocation.js b/src/model/SurveyLocation.js index 3e6977c..fb4ad4a 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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.4.9 + * @version 1.4.10 */ class SurveyLocation { /** diff --git a/src/model/SurveyLocationCoordinates.js b/src/model/SurveyLocationCoordinates.js index 7bb254b..ead888d 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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.4.9 + * @version 1.4.10 */ class SurveyLocationCoordinates { /** diff --git a/src/model/SurveyWithMaps.js b/src/model/SurveyWithMaps.js index 1946c40..4f79bb6 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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.4.9 + * @version 1.4.10 */ class SurveyWithMaps { /** diff --git a/src/model/Svg.js b/src/model/Svg.js index e0944eb..4e3cb89 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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.4.9 + * @version 1.4.10 */ class Svg { /** diff --git a/src/model/SvgG.js b/src/model/SvgG.js index 517c959..12814c6 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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.4.9 + * @version 1.4.10 */ class SvgG { /** diff --git a/src/model/SvgGImage.js b/src/model/SvgGImage.js index ac42e7c..cf59798 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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.4.9 + * @version 1.4.10 */ class SvgGImage { /** diff --git a/src/model/TeachingPeriods.js b/src/model/TeachingPeriods.js index 4dfc190..fc231c0 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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.4.9 + * @version 1.4.10 */ class TeachingPeriods { /** diff --git a/src/model/Timetable.js b/src/model/Timetable.js index 7cd2392..1e6e33c 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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.4.9 + * @version 1.4.10 */ class Timetable { /** diff --git a/src/model/UserData.js b/src/model/UserData.js index 030b0cb..e3befb4 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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.4.9 + * @version 1.4.10 */ class UserData { /** diff --git a/test/api/AnalyticsApi.spec.js b/test/api/AnalyticsApi.spec.js index 2b04bb3..939c20a 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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 index 0b0735b..320d172 100644 --- a/test/api/LibCalApi.spec.js +++ b/test/api/LibCalApi.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.4.9 + * The version of the OpenAPI document: 1.4.10 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/api/OAuthApi.spec.js b/test/api/OAuthApi.spec.js index 00b017f..1c3b8ea 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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 4835f71..62f0388 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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 49b6526..0e42e3e 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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 6de7a58..effdb3f 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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 c506233..9a9bdfe 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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 83c4a18..788c251 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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 2f2a77e..44e44a8 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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 4c04dbb..ec9d572 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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 3ae9768..607fc6a 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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 66f82c3..f4e891f 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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 b641f88..8d9f26b 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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 98afadf..04fabe2 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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 945736a..33f5926 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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 d3b9baa..7ce7d98 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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 64a6047..23dbd4d 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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 149cee9..957e354 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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 0382fe6..f123779 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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 e96ce3e..683fdba 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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 ba0ee3a..3385a27 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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 96d96bf..57d88a1 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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 728997e..88fee0f 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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 fa8f2ea..a494ef9 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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 e0a4d27..6bcb44f 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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 8957ad4..dee7be1 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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 db3ce57..e262c0b 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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 a137bf3..29706c2 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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 5c49044..e54c173 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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 3380d61..1a54fe7 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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 060e808..4494903 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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 f993c73..ce4acd6 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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 1d122d9..eed78f4 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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 4ee6d67..0395425 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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 4a6c3fb..638d4c0 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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 c2cf94b..8e18447 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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 06f448c..53737db 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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 58ffc2a..672a789 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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 1dbccca..f0f631b 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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 913c211..bad4d3d 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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 f797de9..98cf59c 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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 b08338d..6b347b0 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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 4063908..99d7571 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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 3670993..96280e0 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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 ed1c8de..72dc9ee 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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 8730ee5..08d0606 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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 6544c7d..af776d0 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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 10f12fb..a3cc5ad 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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 index 125b11e..bce8ea0 100644 --- a/test/model/InlineResponse20027.spec.js +++ b/test/model/InlineResponse20027.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.4.9 + * The version of the OpenAPI document: 1.4.10 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/InlineResponse20028.spec.js b/test/model/InlineResponse20028.spec.js index de739b3..017c0ff 100644 --- a/test/model/InlineResponse20028.spec.js +++ b/test/model/InlineResponse20028.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.4.9 + * The version of the OpenAPI document: 1.4.10 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/InlineResponse20029.spec.js b/test/model/InlineResponse20029.spec.js index 6505925..cb4f73d 100644 --- a/test/model/InlineResponse20029.spec.js +++ b/test/model/InlineResponse20029.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.4.9 + * The version of the OpenAPI document: 1.4.10 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/InlineResponse20029Categories.spec.js b/test/model/InlineResponse20029Categories.spec.js index 833ac7d..e6b1f29 100644 --- a/test/model/InlineResponse20029Categories.spec.js +++ b/test/model/InlineResponse20029Categories.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.4.9 + * The version of the OpenAPI document: 1.4.10 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/InlineResponse2003.spec.js b/test/model/InlineResponse2003.spec.js index 769d2dc..9af5df2 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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 index 684f88f..4f41d91 100644 --- a/test/model/InlineResponse20030.spec.js +++ b/test/model/InlineResponse20030.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.4.9 + * The version of the OpenAPI document: 1.4.10 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/InlineResponse20031.spec.js b/test/model/InlineResponse20031.spec.js index 0e38d9b..fe09e2b 100644 --- a/test/model/InlineResponse20031.spec.js +++ b/test/model/InlineResponse20031.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.4.9 + * The version of the OpenAPI document: 1.4.10 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/InlineResponse20032.spec.js b/test/model/InlineResponse20032.spec.js index 972d884..c5ae476 100644 --- a/test/model/InlineResponse20032.spec.js +++ b/test/model/InlineResponse20032.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.4.9 + * The version of the OpenAPI document: 1.4.10 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/InlineResponse20033.spec.js b/test/model/InlineResponse20033.spec.js index 48b69a5..965b3e9 100644 --- a/test/model/InlineResponse20033.spec.js +++ b/test/model/InlineResponse20033.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.4.9 + * The version of the OpenAPI document: 1.4.10 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/InlineResponse20034.spec.js b/test/model/InlineResponse20034.spec.js index 6d2808a..3ac8b22 100644 --- a/test/model/InlineResponse20034.spec.js +++ b/test/model/InlineResponse20034.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.4.9 + * The version of the OpenAPI document: 1.4.10 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/InlineResponse20035.spec.js b/test/model/InlineResponse20035.spec.js index 385ac41..1bf6c12 100644 --- a/test/model/InlineResponse20035.spec.js +++ b/test/model/InlineResponse20035.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.4.9 + * The version of the OpenAPI document: 1.4.10 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/InlineResponse20036.spec.js b/test/model/InlineResponse20036.spec.js index 905f61f..672ee4a 100644 --- a/test/model/InlineResponse20036.spec.js +++ b/test/model/InlineResponse20036.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.4.9 + * The version of the OpenAPI document: 1.4.10 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/InlineResponse20037.spec.js b/test/model/InlineResponse20037.spec.js index 8d770a2..d04e1c1 100644 --- a/test/model/InlineResponse20037.spec.js +++ b/test/model/InlineResponse20037.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.4.9 + * The version of the OpenAPI document: 1.4.10 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/InlineResponse20038.spec.js b/test/model/InlineResponse20038.spec.js index 4697b7f..8fc43ec 100644 --- a/test/model/InlineResponse20038.spec.js +++ b/test/model/InlineResponse20038.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.4.9 + * The version of the OpenAPI document: 1.4.10 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/InlineResponse20039.spec.js b/test/model/InlineResponse20039.spec.js index 29c26f0..0b09a87 100644 --- a/test/model/InlineResponse20039.spec.js +++ b/test/model/InlineResponse20039.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.4.9 + * The version of the OpenAPI document: 1.4.10 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/InlineResponse2004.spec.js b/test/model/InlineResponse2004.spec.js index d133404..dd24e88 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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 index 4aa41a4..e9664a6 100644 --- a/test/model/InlineResponse20040.spec.js +++ b/test/model/InlineResponse20040.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.4.9 + * The version of the OpenAPI document: 1.4.10 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/InlineResponse20041.spec.js b/test/model/InlineResponse20041.spec.js index 55bde5d..6da98bb 100644 --- a/test/model/InlineResponse20041.spec.js +++ b/test/model/InlineResponse20041.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.4.9 + * The version of the OpenAPI document: 1.4.10 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/InlineResponse20042.spec.js b/test/model/InlineResponse20042.spec.js index 268a1fc..6f9b514 100644 --- a/test/model/InlineResponse20042.spec.js +++ b/test/model/InlineResponse20042.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.4.9 + * The version of the OpenAPI document: 1.4.10 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/InlineResponse2005.spec.js b/test/model/InlineResponse2005.spec.js index 6d3c891..12fe38c 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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 172e083..08a8118 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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 9e224ef..cebc581 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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 50260be..4c35f3d 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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 31c5fb0..4e5fe5c 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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 24f4cd5..fe8a227 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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 d3fbd20..09abe7e 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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 index 69bd119..69b2405 100644 --- a/test/model/LibcalBooking.spec.js +++ b/test/model/LibcalBooking.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.4.9 + * The version of the OpenAPI document: 1.4.10 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/LibcalCategory.spec.js b/test/model/LibcalCategory.spec.js index 85cbe75..6f31b1e 100644 --- a/test/model/LibcalCategory.spec.js +++ b/test/model/LibcalCategory.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.4.9 + * The version of the OpenAPI document: 1.4.10 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/LibcalForm.spec.js b/test/model/LibcalForm.spec.js index faa65f4..81bec70 100644 --- a/test/model/LibcalForm.spec.js +++ b/test/model/LibcalForm.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.4.9 + * The version of the OpenAPI document: 1.4.10 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/LibcalFormField.spec.js b/test/model/LibcalFormField.spec.js index 589e8c5..d3e3cb5 100644 --- a/test/model/LibcalFormField.spec.js +++ b/test/model/LibcalFormField.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.4.9 + * The version of the OpenAPI document: 1.4.10 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/LibcalLocation.spec.js b/test/model/LibcalLocation.spec.js index a39e9b4..2b78571 100644 --- a/test/model/LibcalLocation.spec.js +++ b/test/model/LibcalLocation.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.4.9 + * The version of the OpenAPI document: 1.4.10 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/LibcalLocationBase.spec.js b/test/model/LibcalLocationBase.spec.js index 2213b90..ab64e80 100644 --- a/test/model/LibcalLocationBase.spec.js +++ b/test/model/LibcalLocationBase.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.4.9 + * The version of the OpenAPI document: 1.4.10 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/LibcalPersonalSeatBooking.spec.js b/test/model/LibcalPersonalSeatBooking.spec.js index 51c95fd..0c57bfb 100644 --- a/test/model/LibcalPersonalSeatBooking.spec.js +++ b/test/model/LibcalPersonalSeatBooking.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.4.9 + * The version of the OpenAPI document: 1.4.10 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/LibcalReserveRequest.spec.js b/test/model/LibcalReserveRequest.spec.js index 49bc1cd..f2cd3e6 100644 --- a/test/model/LibcalReserveRequest.spec.js +++ b/test/model/LibcalReserveRequest.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.4.9 + * The version of the OpenAPI document: 1.4.10 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/LibcalReserveRequestBooking.spec.js b/test/model/LibcalReserveRequestBooking.spec.js index 12c7ef0..815bd1d 100644 --- a/test/model/LibcalReserveRequestBooking.spec.js +++ b/test/model/LibcalReserveRequestBooking.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.4.9 + * The version of the OpenAPI document: 1.4.10 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/LibcalSeat.spec.js b/test/model/LibcalSeat.spec.js index 2cc1f1f..3fca9f1 100644 --- a/test/model/LibcalSeat.spec.js +++ b/test/model/LibcalSeat.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.4.9 + * The version of the OpenAPI document: 1.4.10 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/LibcalSeatBooking.spec.js b/test/model/LibcalSeatBooking.spec.js index 09e5a4a..5033959 100644 --- a/test/model/LibcalSeatBooking.spec.js +++ b/test/model/LibcalSeatBooking.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.4.9 + * The version of the OpenAPI document: 1.4.10 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/LibcalSpaceBase.spec.js b/test/model/LibcalSpaceBase.spec.js index 18a5647..8294b33 100644 --- a/test/model/LibcalSpaceBase.spec.js +++ b/test/model/LibcalSpaceBase.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.4.9 + * The version of the OpenAPI document: 1.4.10 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/LibcalUtilisationSeatSummary.spec.js b/test/model/LibcalUtilisationSeatSummary.spec.js index 545bf25..9b463b2 100644 --- a/test/model/LibcalUtilisationSeatSummary.spec.js +++ b/test/model/LibcalUtilisationSeatSummary.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.4.9 + * The version of the OpenAPI document: 1.4.10 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/LibcalUtilisationSpaceSummary.spec.js b/test/model/LibcalUtilisationSpaceSummary.spec.js index 68d3435..6e374cb 100644 --- a/test/model/LibcalUtilisationSpaceSummary.spec.js +++ b/test/model/LibcalUtilisationSpaceSummary.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.4.9 + * The version of the OpenAPI document: 1.4.10 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/LibcalZone.spec.js b/test/model/LibcalZone.spec.js index 38b8025..ad0bbbe 100644 --- a/test/model/LibcalZone.spec.js +++ b/test/model/LibcalZone.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.4.9 + * The version of the OpenAPI document: 1.4.10 * Contact: isd.apiteam@ucl.ac.uk * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/test/model/Location.spec.js b/test/model/Location.spec.js index 614a1d9..2b51339 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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 e6fc065..99a6d01 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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 6901b95..aed35df 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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 4b9b20e..5ecffa3 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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 1230d79..d07fa4d 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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 9825d67..1a9f9c8 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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 f1b163d..9faf267 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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 1d94691..9392a5f 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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 2040d61..0130b76 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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 1475804..8366d96 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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 7f392a2..4eb7f47 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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 ae943c3..9a49c11 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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 bf58242..5f90a67 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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 6fe9af3..0f11ea8 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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 4df411c..bff1dc0 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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 244d898..fb18714 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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 86a1c5c..d849d1b 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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 17f3e8a..a184f0c 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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 1bcdd7a..5736112 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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 07a082c..157b669 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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 546ac1b..6dfc71a 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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 51f9d64..87241a0 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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 2a3c3f5..3f59cde 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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 1a61955..4924e61 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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 f512451..6ec74bb 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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 3c08d90..5b63124 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.4.9 + * The version of the OpenAPI document: 1.4.10 * 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 283ee6f..ddb8102 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.4.9", + "version": "1.4.10", "termsOfService": "https://github.com/uclapi/uclapi/blob/master/backend/uclapi/uclapi/UCLAPIAcceptableUsePolicy.txt", "license": { "url": "https://github.com/uclapi/uclapi/blob/master/LICENSE",