API features

[kmccurley]

Your first start at the openapi definition looks like it was a huge undertaking, and I'm sure it will have a good payoff for future work. I'm not familiar with the use of openAPI, but I had a couple of comments relevant to this that may become issues for the future. I'm not sure if this fits exactly what you wanted for issues on the API, so feel free to treat as you see fit.

1. we use hotcrp as the first phase of our publishing pipeline, namely the review phase. For papers that are ultimately accepted, there are still two steps for authors to implement, namely the copyright/license agreement and the upload of final versions to the copy editing and production system. We provide links in hotcrp for authors to complete these tasks in external systems. For this purpose we need the ability to retrieve the list of accepted papers and the full public metadata associated with a given paper (e.g., author information, abstract, title, ID, long paper/errata/SoK type, but not review score or conflicts). Once the author has completed these phases, we make API callbacks into hotcrp to set the correct PaperOption so that the PC chair/editor can see which papers have completed these phases. Our implementation is fairly invasive because it depends upon the "final version" PaperOption to have a fixed ID so that we can update the database. You might want to standardize this kind of interaction with external systems.
2. There is some metadata like deadlines, acceptance rates and the list of PC committee members that need not require authentication but might help the community in doing data mining on the submission and peer review process.
3. Most of the difficulties that I've had in modifying hotcrp arise from the fact that rendering is done server-side with no template system. That makes it difficult to determine from looking at the code what renders a specific piece of the UI. It would probably help in the maintainability and understandability if you moved to either client-side rendering or server-side rendering with a template system. OJS has announced that they are moving to client-side rendering using vue.js with a well-defined API such as yours. Their review model is of course different, so the API doesn't align exactly with what you have, but you might consider following this path in order to separate UI rendering from the backend. This would be a gigantic undertaking but might help in maintaining the code going forward. I don't have a strong opinion about client-side rendering vs server-side rendering, but a template system like Twig or laravel/blade might help to make the code more readable.
4. OpenReview.net also has an API specification. They went so far as to define entities that are common objects to refer to in their API. Their entities are fairly generic like Note, Edge, Edit, etc. I'm not sure if these represent actual objects in their database, but maintaining consistency between the schema for these objects and an API can be problematic. It looks like your api components are only referred to by IDs, which means you don't have to deal with keeping the schema updated for entities that you retrieve and modify. I think openreview.net uses client-side rendering but their system is not open source so it's hard to tell for sure.