Update deprecated API reference

[jdsutherland]

These changes update the docs to reflect the current API location.

[rpottsoh]

@iHiD or @kytrinyx do you have any thoughts/suggestions here?

[jdsutherland]

I'm pretty much in the dark regarding the details of the API but based on looking at the CLI, it seems that the website repo holds the API that it communicates with: https://github.com/exercism/website/tree/master/app/controllers/api

Currently it's confusing for an outsider as the API referenced in the docs isn't relevant anymore. If the API is intended to be private then the docs should make this clear. Either way, it seems like there is confusion that is worth clearing up here.

[rpottsoh]

A change should be made, but I think some guidance is warranted on what the best form that change should take. I expect at some point the API will be made available to the public, I personally don't know the time frame for that.

[iHiD]

I'm fine with this change, as it's correcting something that's incorrect. I'd also be tempted just to remove the API section.

I expect at some point the API will be made available to the public, I personally don't know the time frame for that.

This is correct and I don't either. I imagine late-2019 at the earliest.

[rpottsoh]

remove the API section.

I think this is the most prudent course of action for the moment since there is nothing publicly available to document.

@jdsutherland would you be able to commit another change that would simply remove the API section for the time being? Or I suppose at the very least a "to do" blurb could be left there instead as a place holder.

[jdsutherland]

Omitting the mention of the API seems counterproductive in terms of the utility of documentation. I think most readers of an architecture doc are coming because they want to understand the components of the Exercism system. "Something is better than nothing" seems more useful here. A reader of this document is likely going to wonder about the backend.

Also, it seems correct that https://github.com/exercism/website/tree/master/app/controllers/api is serving the CLI. Why not mention this?

[iHiD]

The issues it that these docs existed in a time where we accepted PRs to the API etc, so explaining where it was, how it works, was important. As we don't do that now, I'm not sure of the value of this. I'm not sure of the value of the file altogether tbh, but I figured that was too big a question for this issue.

@jdsutherland What's your reason for reading the doc. Understanding that might help us understand what to do.

[jdsutherland]

What's your reason for reading the doc. Understanding that might help us understand what to do.

I was new to open source, looking for a project to contribute to and I'd heard that some of Exercism was rewritten in Go. I started contributing to the CLI and wondered more about how Exercism works so I searched and found that this docs repo has an Architecture doc.

The issues it that these docs existed in a time where we accepted PRs to the API etc, so explaining where it was, how it works, was important. As we don't do that now, I'm not sure of the of this. I'm not sure of the of the file altogether tbh, but I figured that was too big a question for this issue.

I was under the impression (e.g. https://exercism.io/about) that all of Exercism was open source and open for contributions but it seems that isn't quite the case. I'm not sure if that is made clear to those interested in contributing though.

[kytrinyx]

all of Exercism was open source and open for contributions but it seems that isn't quite the case.

All of Exercism is open source. Every single part of Exercism is distributed under an open source license.

We don't however, generally accept contributions to the exercism/website repository, because we don't have the bandwidth to manage contributions to that repository. It's the core of the product, which means that there's a ton of user experience and design work that every change there relies on. Additionally, we need to be extraordinarily judicious about pulling in code to that repository, since it is the core of the experience, and we hope to maintain it for a very long time. This means that any patch submitted needs very careful review, which requires time and the careful attention. We don't have that time and attention to spare right now to review pull requests to the exercism/website repository.

[jdsutherland]

We don't however, generally accept contributions to the exercism/website repository, because we don't have the bandwidth to manage contributions to that repository.

This is understandable. I want to make it clear that what I've said isn't intended as a complaint or criticism. Perhaps I misunderstood what was previously in this thread about the API - it was previously said:

I know that the API has not been released, so pointing people to the website repo I would agree is better than doing nothing here

I read this as meaning that there is a private API that hasn't been released. The API repo from this Architecture document is deprecated and I'm told the new one hasn't been released. This is what prompted the question of everything on Exercism being open source. I wonder if what's meant in actuality is that there is a private API in the website repo and that a public API is intended to be developed - not there is a private API repo that hasn't been released. I suspect that might be the source of my confusion.

The issues it that these docs existed in a time where we accepted PRs to the API etc, so explaining where it was, how it works, was important. As we don't do that now, I'm not sure of the value of this. I'm not sure of the value of the file altogether tbh, but I figured that was too big a question for this issue.

This makes sense, but from the outside perspective it's not clear to me how anyone would know that this stuff isn't soliciting contributions. My inexperience with open source may be getting there better of me here - maybe it's not reasonable to assume this should be explicit. If you're going to accept contributions for the CLI (for example), it seems worth documenting how the rest of the system fits together though. If you don't want to solicit contributions, than I'd agree that an Architecture document isn't valuable. Currently this seems a bit obscure from the perspective of anyone looking to start contributing.

[kytrinyx]

I read this as meaning that there is a private API that hasn't been released.

Ah, sorry, we were unclear. We haven't documented it. It's not public in the sense that we make no guarantees whatsoever about the stability of the API. It's defined in the github.com/exercism/website codebase.

This makes sense, but from the outside perspective it's not clear to me how anyone would know that this stuff isn't soliciting contributions.

It's been on my list for about 6 months to overhaul the documentation. It is sorely outdated, and terribly confusing.

My inexperience with open source may be getting there better of me here - maybe it's not reasonable to assume this should be explicit.

No, it's completely reasonable to assume that. It's just that I haven't gotten to it. I'm trying to claw my way out of this pile of work, but it's a bit of a ball-and-chain problem. I can't get to where others can meaningfully contribute without doing a bunch of work first.

[macta]

Would just like to add that the pharo-smalltalk track uses that (now) undocumented api to both submit/fetch exercises without shelling out to the go cli (https://github.com/exercism/pharo-smalltalk/issues/96) - so we would like a mechanism to know about breaking changes. We had to do this as it was untenable to shell out and deal with different OS differences (most notably windows) in a cross platform way - where as http is cross platform.

[iHiD]

I'm going to merge this. @macta I'll try and remember to tell you if I do anything that might break the API.

[bencoman]

We haven't documented it. It's not public in the sense that we make no guarantees whatsoever about the stability of the API. It's defined in the github.com/exercism/website codebase.

@kytrinyx, As a halfway house, could you document a pointer to where the API is handled in the codebase? i.e. so we might decipher the API from the route definitions.

[iHiD]

@bencoman It's (sort of) here. I say sort of, because you might also think it more appropriate to point to here. I'd accept a PR to update this PR with either the first or both links.