Welcome to Codidact Meta!
Codidact Meta is the meta-discussion site for the Codidact community network and the Codidact software. Whether you have bug reports or feature requests, support questions or rule discussions that touch the whole network – this is the site for you.
How should a Codidact public API work?
I'm planning to add a public API to Codidact so people can make applications that read Codidact data automatically.
Features and purposes
I have my own purposes in mind for this[1], but there are many other potential uses. Before I start building this, I'd like to hear what features you would like the API to have, and what purposes you might use it for.
General thoughts
Even if you are not planning anything yet, I would still like to hear your thoughts on what might be useful for the future. I'm hoping this discussion will help avoid designing an API that is too specific, or that needs breaking changes later.
Whatever your thoughts, please share them. This could be any of the following or anything else you want to bring up:
- Ideas for projects you might make one day
- Thoughts on the structure of an API
- Things to bear in mind / avoid (I'm new to this, so things that are obvious to you may not be obvious to me)
- Preferred data format(s)
- What to include from the start and what can wait until later
- Limits, such as how many results to permit in a single response (like pagination) and how to handle requesting more
-
I'll add my own personal API requirements in an answer. Please comment on the answer if there's a better approach I should consider. ↩︎
2 answers
I'd like to host contests that read code directly from answers
Here's what I'd like to see in an API to allow me to host coding contests on Code Golf Codidact.
Essential
This is the only feature I would need in order to start hosting contests.
The answer content for each answer to a specified question
This allows extracting the code block that constitutes a contest entrant from an answer programmatically, rather than needing to manually paste code into the contest controller each time there is a new answer or an edit to an existing one. This allows anyone to run a tournament in their browser without needing to download or install anything, and without needing to wait for the contest host to update anything.
I can imagine this working in one of two ways:
-
A single API call including the question id, which returns all answers to that post. These could be in the form of a JSON object with answer ids as keys and answer objects as values. Each answer object could have keys "user_id", "user_name", and "content", showing the raw text content of the answer.
-
Two types of API call:
- First a call including the question id, which returns a list of all the answer ids under that question.
- Then a call including an answer id, which returns the answer object for that answer (similarly, with keys "user_id", "user_name", and "content").
This would mean one API call to get the list of answer ids, then one API call for each answer to get its content.
Nice-to-have optional extras
For me, these are not necessary in order for me to start hosting contests, but I would be likely to use them if they existed.
The comments on a specified post
This allows the contest host to add comments to answers that then affect the behaviour of the contest controller. For example, adding a comment containing the word "disqualified" could cause the contest controller to exclude that answer from tournaments.
I can imagine this working in one of two ways:
-
A single API call including the post id, which returns all comments to that post. These could be in the form of a JSON object with thread ids as keys and thread objects as values, with each thread object having comment ids as keys and comment objects as values. A comment object could have keys "user_id", "user_name", and "content" for the raw text content.
-
Three types of API call:
- First a call including the answer id, which returns a list of all the thread ids under that answer.
- Then a call including a thread id, which returns the thread title and a list of all the comment ids under that thread[1].
- Then a call including a comment id, which returns the comment object for that comment (similarly, with keys "user_id", "user_name", and "content").
This would mean one API call to get the list of thread ids, then one API call for each thread to get the list of comment ids, then one API call for each comment to get its content. This would be more calls to the server, but each would be smaller and also this would allow terminating early if a comment containing "disqualified" is found.
The edit history of a specified answer
This would allow specifying a date in the contest controller, and running a tournament with the answers as they were at that date. This could be interesting for contests where the answers evolved over time and watching a tournament play out with the latest versions only tells half the story. It would also allow showing a chart of different answers rising and falling over time, rather than just a final leaderboard.
I can imagine this working in one of two ways:
-
A single API call including the post id, which returns all versions of that post. These could be in the form of a JSON object with version ids as keys and version objects as values. A version object could have keys "user_id", "user_name", and "content" for the post raw text content.
-
Two types of API call:
- First a call including the post id, which returns a list of all the version ids in the edit history.
- Then a call including a version id, which returns a version object including the raw text content for that version of the post[2].
This would mean one API call to get the list of version ids, then one API call for each version to get its content.
-
Would this be better split into two calls - one for the title and one for the comment ids? ↩︎
-
For me, the content for that version is what is required, but for other purposes it might be useful to have the before and after comparison as shown in the user interface. Should this be split into two separate API calls so that people can request just the one they need? ↩︎
0 comment threads
I'd like to make charts of user and community stats
These could involve a large amount of data as the site grows, so should probably be links to a location that generates them once a day and/or caches them so they don't use the API every time someone views them.
This is a non-exhaustive list of charts that might be of interest.
A user's reputation over time
This would need similar data to the vote summary tab of the user page - a summary of votes per day, and additionally how much reputation each vote is worth.
For charts that do not start at the date a user joined a community, it would also be useful to be able to request a user's reputation at a given date, rather than request all the data back to their joining date just to calculate their reputation at the start of the chart period.
A user's raised and fixed bugs and feature requests over time
Would this be better as:
- A simple request for a user's posts including date of posting and tags, followed by a request for the edit history to see when a "status-completed" tag was added?
- A request for a summary per day of a user's bugs and feature requests (the API doing some of the work for you)?
Probably best to implement the simpler, more general approach first, then add more efficient, more specific approaches if and when needed (such as if it is decided to include certain charts as part of the Codidact user interface).
A community's/tag's questions/answers per day
For a whole community, requesting all of the questions/answers just to then count how many were posted each day seems an unreasonable demand to place on the server. Should we have the ability to request posts that meet certain criteria, much like the filters in the current user interface?
- Post ids that were posted on a specified date?
- Post ids that have a specified tag?
Would it be useful to also have a similar request that only returns the count of how many matches, rather than the list of post ids?
A community's unanswered questions over time
Similarly here, it is technically sufficient to be able to request all posts, and the number of answers per post, but that seems an unreasonable demand to place on the server. Here we might need slightly more fine grained filters than in the current user interface:
- Filter by min/max number of answers (max zero for this specific use case).
- Apply a date to the previous filter. Unlike in the user interface where we only need to know how many answers a question has now, here we would need to know how many answers a question had at different dates over a date range.
0 comment threads
4 comment threads