Great to hear! We have not had 3rd party apps try to use this API before so please let us know how it goes and if there are things we can improve that would make your integration easier.
Hi @rrrrrok . I’m researching how to use the Renku 2.0 API as part of a Learning Management System.
In this case, a “course author” would be using my LMS system to define a connection to Renky, and then the LMS would be calling Renku via the API anytime a student needed to spin up a copy of the course author’s resource.
I’m wondering if the LMS needs to save some kind of credentials for the course author at set up time, and then at certain times the LMS would use the Renku 2.0 API to, for example, copy a Renku notebook from the course author’s account to a student’s account (behind the scenes) and then show it to the student.
Can you reiterate how, in this example, the API should be accessed? (Again, this would be for Renku 2.0).
Does the LMS store the course author’s Renku username and password and then call an endpoint to retrieve a token, which could then be used for all further API calls (for a limited time)?
Or is there a simpler way to store an “Authorization: Bearer (some token)” token that can just be passed in the header for any API call?
Thanks for elaborating on the process for Renku 2.0. I tried reading through the above but I’m not sure if it’s still relevant. For example, I can’t find keycloak pages that show things like you show in your screenshot above.
Thanks for your help!
I’m not exactly sure what you mean by copying a renku notebook, we don’t really have a notebook concept, just projects, sessions, environments, data sources/connectors, and repositories. Or do you mean a jupyter notebook in a repository?
Yes this is how our API works currently. But for our use it sits behind an API gateway that will replace the users session with an up to date token for API requests, since the tokens themselves are not long lived (a couple of hours on renkulab).
We have a story to implement getting more long lived API tokens for users, which we still need to work out the details for. Roughly speaking, there will be some page where a user can generate a long lived api token and they can then use that to access the API. We are looking for users that could drive that use case, so I’ll refer you to our product owner @laura.kinkead.
@ralf.grubenmann Yes sorry! I meant to say a Jupyter Notebook (or any compute-intensive resource for an e-learning course, really) inside a Renku project.
A long-lived token would be good because then a course author could save it in the LMS, and then the LMS could continually use that token over time to launch resources for a student (for which that student is authorized).
My assumption is that when a student is taking course and comes to a unit where it’s time to show the student a particular Renku project resource, the LMS will use the API to copy the resource from the course author’s Renku account to a student account, and then spin up the resource under the student’s account before directing the student to it. (I guess this means the student must already have a Renku account before taking a course? Or perhaps there’s a way to auto-create a student Renku account, or perhaps just do an anonymous session.)
For security, a course author could occaissionally rotate their token by whatever mechanism Renku provided, and then just update it in the LMS. This is a pretty basic system but low-complexity and easy to implement.
I’m interested in building a test case for my LMS, so @laura.kinkead let me know if you’d like any more input on a simple use case 
one thing to note here is that the Renku API is purely for dealing with Renku “things”. A jupyter notebook would be stored in a git repository linked to Renku (or maybe in some cloud storage), but the repository itself is not managed by Renku, i.e. there’s no API for adding things to repositories or anything of the sort. Renku can help broker access in some cases by storing credentials, but managing what’s in these third party places is not something we do, outside of having the interactive session as a convenient place for bringing various third party services together.
What I’m trying to say is, you can use the API to spin up a session, get metadata about a project, etc. But for your example of coping a jupyter notebook from the course authors account to a students account, I imagine this would involve cloning the course authors git repository and the students git repository somewhere, copying the file over to the student’s repo and then committing and pushing the changes (or using something like the github api to the same effect). Same story if the notebook is in cloud storage.
Renku can give you information on what the git repositories or cloud storage in question are, but its API does not offer this kind of functionality for manipulating the content of these third party resources, and we don’t have any plans of adding that kind of functionality outside of a few very specific use-cases. We are considering a way of applying some form of repository template (think cookie cutter) to users git repositories as a convenience feature, but that’s the only feature I’m aware of where we would directly change the contents of a repository for a user.
So a workflow for your example could look more like using Renku to know all the pieces involved in the process and then the LMS itself interacting with the github API to perform the necessary changes, based on the metadata gathered from Renku.
Alternatively, I could see a scenario where a course author has many git repositories, each containing a single notebook, linked in the course authors Renku project. And then you could link those repositories to students’ projects, adding a new one every week. So not doing it on a file basis, but on a repo basis. Each repo would show up as a new folder in a students session, which I think addresses your use-case. But Renku does not broker access to those repos, so they would have to be made public through the github API or the students would have to be added to each repo with the right permissions when the time comes, manually or through the github API.
The other big difference with this is that each repo would still be a single repository, not a copy/fork for each student, so if the students are expected to edit the contents of these repositories in place, this wouldn’t work.
Thanks for that thoughtful answer, @ralf.grubenmann . So the more involved workflow I was thinking of wouldn’t be possible, but it sounds like a very basic integration is possible. Based on what you said above, it sounds like Renku could be used in a course in the following way:
- The course author creates, say, five public GitHub repos for five Jupyter notebook-based exercises that happen in a course.
- The LMS uses the API to spin up an anonymous session in Renku for the student when they encounter one of these exercises. The student won’t be able to save anything but at least they can interact with the Jupyter notebook to better understand a concept via e.g. a python simulation library.
My assumption here is that Renku does give me the ability to spawn a public github repo (the instructor’s) for an anonymous user, so I don’t have to require the student to have an account with Renku or with GitHub.
If so, this only leaves the question about what (long-lived) credentials the LMS would use when calling the Renku API, which I think is something your team is still working on.
yes, that sounds correct to me.
You could extend the integration in your example like:
- The course author creates, say, five public GitHub repos for five Jupyter notebook-based exercises that happen in a course.
- The LMS uses Githubs api to fork/copy the repositories for each student, using a github api token and give the student access through the github api.
- The LMS uses the API to spin up an anonymous session in Renku for the student when they encounter one of these exercises with the copied repository. if the LMS also had the students Renku token, then it could instead spin up a non-anonymous session that the student can save changes in, with the copied repository, as long as they also have their github account linked with Renku.
but this would be strictly on the LMS+Github side and not functionality that Renku offers. This requires both authors and students to have accounts in Renku, the LMS and Github, and to get Renku API tokens and put them into the LMS.
This could be streamlined a bit with Renku offering OAuth2 access to make it easier for users on the LMS side to connect to Renku (then the LMS could just have a “connect with Renku” button instead of copying API tokens around). I think this is something we want to do further down the line but it’s definitely not on our current roadmap.
There might also be a solution where both the LMS and Renku use the same Keycloak instance (or federated keycloak instances), so every LMS user is automatically a Renku user, but that needs a dedicated Renku deployment and would involve quite a bit of effort. Or Renku could offer logging into Renku with LMS accounts, similar to how you can use ORCID or EduId logins. Just to name some possibilities, but again, this would take some effort so support.
Hi @danielmcquillen!
To start, here’s what I could see you could do right now in Renku 2.0 for your use case. It doesn’t have all the polished integrations you’re talking about yet, but it’s something you could do today:
- The instructor creates a public GitHub repository with the 5 Jupyter notebooks for the exercises.
- The instructor creates a public Renku 2.0 project and attaches that public GitHub repo.
- The instructor also adds a session launcher to the project that provides the environment the students need to do the exercises (using one of our template environments, or creating your own with a custom set of packages pre-installed).
- The instructor adds a link in the LMS to the Renku 2.0 project.
- Student: From the LMS, follow link to the Renku project, clicks launch, and they’re in the session. They can open the specific exercise notebook inside the session.
(Alternatively, the instructor could set up multiple repos and Renku projects, one for each exercise, so the student doesn’t have to remember which exercise notebook to open once they’re in the session.)
With this approach, the students don’t need a Renku account or a GitHub account (they are running anonymous sessions on the Instructor’s project, which uses only public code repositories). No credentials of any kind are passed between the LMS and RenkuLab. However, this comes with the tradeoff that students can’t save their work.
…
Then, there’s a number of ways we can smooth out this flow:
If it’s a priority for you to have the student’s experience involve fewer steps, we could develop a session start link (we have this in Renku 1.0), where the instructor could get a URL from their project that directly launches a project’s session launcher, so the student goes directly from the LMS to the Renku session, skipping the project page with the launch button. This also doesn’t require any credentials to be passed between the LMS and RenkuLab.
If it’s a priority to enable the student to save their work, we have a feature under consideration for our next development cycle to allow students to make their own copies of Renku projects, where they can modify the project to create a place to save their work. I believe you came across the feature design document for this when it was still a stub, and I have recently updated it with the latest feature proposal 
If it’s a priority that the instructor doesn’t have to set up the Renku project(s) manually, I could imagine that we could potentially extend our API so one could programmatically start a session with a provided code repository and environment outside of the context of a Renku project… but this represents a significant departure from our current focus, so it would have to be a discussion
Thank you for taking the time for this discussion! Let me know what you think.