Define a public API

[NobbZ]

Lets define a public API which we can use to write our own clients.

An API which makes us as students and mentors able to not leave our editor of choice.

Given an appropriately defined API a student were able to see comments of a mentor directly in his editor, could reply to them and submit a new solution in a single go.

Mentors could see their queue and directly download solutions, test them, etc, possibilities are plenty…

[iHiD]

@NobbZ Very keen to do this. The current API is effectively public but undocumented. Once it's stable with the CLI, we'll document it and then can take feature requests for individual features. I'll mark this as a discussion and you and others can suggest functionality you'd like to be able to access here.

[iHiD]

Relevant: https://twitter.com/andrewradev/status/1023151506604867585

[NobbZ]

I'll quote myself from the slack here, as not everyone can join that discussion and this is not only relevant for mentors, but maintainers or students as well:

I've heard about that vim-wrapper, but thats not what I am talking about. That plugin does not offer any more as the CLI does. What I was thinking about was full exercism integration into an editor through publishing and opening the API specs. Such that (given I've driven my plugin thus far) I could replace the page by my editor.

[iHiD]

I wasn't suggesting they were the same thing, as much as that that plugin might be another consumer of the API.

[NobbZ]

I never understood it like that, but comparing to this plugin helped me to better describe what this suggestion is about.

[ErikSchierboom]

This would be great to help with creating automated tools involving exercism (e.g. for downloading tests and running them).

[iHiD]

Make me a list of the things and I will make it so. I like writing APIs :)

[hoovercj]

I'm very interested in this. I'm quite keen to solve exercises and mentor students without leaving VS Code

[iHiD]

Could you all make a list of the functionality you need pls?

The obvious ones for me are:

• Download solution
• Submit solution

Both of which are in the API, just not documented. If you can give me a list of the functionality you need I will start thinking it through.

[hoovercj]

This will be my "living list" as I think of things. I almost made an extension back when nextercism was first announced to wrap the CLI but other projects got in the way and I've forgotten what I had planned :-)

But as far as things I'd like outside of the CLI:

• Iterations
  • Utilize editor diff views to diff iterations (both for mentors and students)
  • This might be the most important
• Solution Comments
  • Take feedback into account in the editor / see students explanation in the editor
  • Allow posting comments
• Mentor Queue Information
  • View queue
  • View solutions per exercise (as available in the site now)
  • Allow approving, commenting, etc. (least important request)

My naive thought is that it would be great to be able to get the files in the body of responses and not in files. For example, if I want to get the different iterations of the solution for a single file, I just want the text contents to pass to the editor, I don't want a zip file that I have to process. At least for the early solutions this should be sufficient.

[xiegeo]

Here is my list for what I could use an API for:

• Build missing features. Such as suggesting a random task from unlocked tasks. If I want a feature that's not provided by the website or CLI, I could build my own to an API. If the feature is really useful, it can be included by the official tools.

• Integrate with other services. For example, I can show my latest accomplishments in exercism on my personal website.

• Data analyze. Download and analyze different solutions to the same tasks. For example, find fastest, shortest, or classify solutions by technic. Make it easier to find unique and interesting solutions.

[bencoman]

@iHiD, Pharo is derived from Smalltalk, and similarly doesn't work with code stored in files but stored in-Image instead. So we're forging ahead with our IDE interface to Exercism. From examining exercism --verbose we already have exercise downloading working(exercism/pharo-smalltalk#32), and submitting seems feasible(exercism/pharo-smalltalk#96). The next most useful function is retrieving a list of exercises available to download, for presenting in a menu. (I read somewhere to old CLI had this.) We would make use of this as soon as it is available.

The workaround I was thinking of was sucking the full exercise list out of the github repo,
or just hardcoding the list in our tool, but it will be awkward filtering on student progress without the knowledge maintained on Exercism server.

[macta]

@bencomam the list of exercises can come from the config.json which is in the repo - better if the api exposed that, but a workaround is to use that file.

[sshine]

Could you all make a list of the functionality you need pls?
The obvious ones for me are:

• Download solution
• Submit solution

As a mentor I'd like exercism comment [--approve] feedback.md, since what I'm doing right now is give feedback and then copy-paste it into a text file in their directory, so that I can search for feedback I've already given and copy-paste when applicable. With an exercism comment function I could do it the other way around.

(I'd like queue control as a command-line feature as suggested by @NobbZ in the issue description, but not as urgently as exercism comment [--approve] feedback.md.)

[sshine]

Add public API functions for inspecting the progress of language track queues (suggested in #4167):

I would very much like statistics on how a track is progressing.

I imagine a bar chart across time that contains:

• How many (non-)Core exercises are in the queue
• How many new (non-)Core exercises were put in the queue for each day in the last month.
• How many (non-)Core exercises were popped from the queue (across all mentors).

[...] Perhaps if these statistics could be prioritised as an API feature, we can leave initial statistics renderings as user tools, since the bar for adding command-line tools to a language track is lower than adding production-value pages to the website.

[samWson]

You might be interested in this. For the exercism/pharo language track we have been making our own client using the API so to speak.

Smalltalk, and by extension Pharo, lives inside its own development environment where you are always dealing with objects instead of files. Trying to integrate this with the exercism command line tool caused us problems, so we instead fetch and submit exercises directly using HTTP requests to api.exercism.io.

We only just recently got this working. At the moment all it can do is fetch and submit exercises.

[bencoman]

And for concrete sample code, we have ExercismCommand with subclasses...

• ExercismDownload
• ExercismSubmit

and tests...

• ExercismDownloadtest
• ExercismSubmitTest

[NobbZ]

Please remember that this was not asked, only to be able to download and submit, this was also asked to be able to operate the full site without leaving my editor of choice.

• Browsing my tracks as a student
• Choose/Update exercises
• Submit solutions
• Read and answer a mentors feedback
• Browse exercises that needs mentoring as a mentor
• give feedback as a mentor
• Basically: make me able to drop the webbrowser

[uzilan]

It would also be nice if I could draw statistics about my own progress - which tracks I've joined, how many exercises I've done and how many are waiting etc - would be awesome to be able to show that as charts (for example in my github exercism solutions repo)

[iHiD]

@diabolicle For what purpose?

[IsaacG]

I'd really enjoy an API endpoint which allows me to check for new notifications.

[LeaveNhA]

I've made something but I don't know it's still relevant.

https://github.com/LeaveNhA/exercism-layer

[NobbZ]

I wasn't able to find any meaningfull code in that repository that actually calls out to the exercism tool or API.

Also most of the output on the GIFs does look like the old output from the v2.x CLI.

Also the age of the last commit (2 years) makes me think, that the repository is meant to work with an old version of exercism that simply does not work today anymore.

Neither does the old CLI work with the current website, nor were the commands compatible with the new CLI, as there is no fetch anymore and they way downloading works in general has been redesigned.

[LeaveNhA]

That's why I wrote it.
I wanted to give something back to community.
If you all aim something like this, I can help you guys.

[ronvoluted]

I understand the API isn't documented but is effectively public. Is there a basic list of current endpoints/methods/etc we can experiment in the dark with?

[iHiD]

@ronCYA The API does what the CLI does. What are you looking to do with it?

[ronvoluted]

@iHiD Oh sorry I didn't know. I've taken a look at the commands in exercism/cli/ now and see I misunderstood what kind of API this is. I wondered if there'd be dummy/test data or an API that would let me pull down published solutions and comments without needing to scrape them.

I'm fascinated with the automated analyser work being done and wanted to research the feasibility/effectiveness of some ideas I had. Mainly, AST-diffing on solutions and natural language understanding on comments. The intent would be to suggest comments for mentors to make, so they could spend more time on the human aspects of mentoring. Sky-pie stuff but worth toying with!

[iHiD]

The intent would be to suggest comments for mentors to make, so they could spend more time on the human aspects of mentoring.

We already do this via the analyzers :) What language(s) are you interested in?

Here's an example from JavaScript:

I wondered if there'd be dummy/test data or an API that would let me pull down published solutions and comments without needing to scrape them.

If you'd like some data to work with, you can reach out to me on our Slack and I can send you something. You can also chat to others working on things there too. Are you a mentor currently?

[cascandaliato]

Is there a public endpoint to get the number of solutions published by a specific user?

I wanted a badge for my exercises repo so I wrote a small scraper but I'd like to use a cleaner solution.

[iHiD]

Nope. There probably will be in v3 (coming later in the year). We also have plans to add badges etc too. Nice work on the scraper :)