Commit b6773320 authored by Alex's avatar Alex
Browse files

Add documentation of API

parent b6a156a6
# imperial_doc_materials
Python client for the [Materials API](https://api-materials.doc.ic.ac.uk/) in DoC
\ No newline at end of file
Python client for the [Materials API](https://api-materials.doc.ic.ac.uk/) in DoC.
## Setup
Add this code to your Flask's ```app.py``` if not done already (it should already be present in the Flask template):
```python
# Add integration to the Materials API
import imperial_doc_materials
imperial_doc_materials.init_app(app)
imperial_doc_materials.set_redirect_url('auth.login')
```
## Using the Materials API in a Flask route
Again, there are examples of this in the template. You must use the ```@using_materials``` decorator before the route function definition. This will give you access to a ```Materials``` client object which you can use to make requests.
```python
@home_blueprint.route('')
@login_required # Indicate that the user must be logged in (via LDAP)
@using_materials # Indicate that we want to access the Materials API
def dashboard(materials_client, user):
my_courses = materials_client.get_courses_for_year("2122")
return render_template('dashboard.html', user=user, my_courses=my_courses)
```
**Important:** if using other decorators such as ```@login_required``` provided by the [imperial_ldap package](https://gitlab.doc.ic.ac.uk/paas-packages/imperial_ldap), the parameters to the function appear in inverse order. For example, in the code above, the login decorator appears first, so the ```user``` parameter provided by it goes last.
## The API
### ```Materials``` class:
- Creating a new client given a username and password:
```client = Materials.create_client(username, password)```
- Getting the list of enrolled ```Course```s given an academic year (of the form "2122"):
```courses = client.get_courses_for_year(academic_year)```
- Getting the list of all the ```Resource```s that are available for a given academic year:
```resources = client.get_resources_for_year(academic_year)```
### ```Course``` class:
The available fields of a ```Course``` instance are:
- ```title``` (string): the full name of the course
- ```code``` (string): the code of the course
- ```has_materials``` (bool): whether the course has any materials uploaded
- ```resources``` (List[Resource]): a list of all the ```Resource```s for that course
### ```Resource``` class:
The available fields of a ```Resource``` instance are:
- ```id``` (int): the internal DoC ID of the uploaded resource
- ```title``` (string): the name of the resource
- ```type``` (string): if the course is a "file" or a "link"
- ```category``` (string): the category of the resource
- ```url``` (string): the URL to the resource
- ```course_code``` (string): the code of the corresponding course
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment