search

freedomofpress / securedrop

GitHub repository for the SecureDrop whistleblower platform. Do not submit tips here!
https://securedrop.org/
Other
3.61k stars 685 forks source link

Formalize SecureDrop's API #6522

Open ghost opened 2 years ago

ghost commented 2 years ago

What

I'd like to see us create a formal API specification for SecureDrop

Description

While working on implementing dynamic testing for SD, I found myself in a situation where it would have been useful to have a formalized OpenAPI specification of the API to facilitate testing.

This got me thinking that there could be a number of uses for having a formal specification of the API beyond testing, including (but not limited to) having a clearly documented API, making it easier to audit the API, and even making it easier for ourselves or other developers to write new clients.

I'm curious to hear what everyone else thinks about it, whether you agree that it would be useful, and if so, how to add this specification? OpenAPI is relatively common for this, but we might want to explore other alternatives.

cfm commented 2 years ago

Thanks for raising this, @l3th3. I'm very much in favor, both in general of this idea and specifically of OpenAPI, though I'm also open to other options. In places like #5104 and freedomofpress/securedrop-client#1549, we'd already benefit from being able to discuss API changes as specification-level diffs well in advance of considering their implementation.

Let me know if you'd like to work together on this!

cfm commented 1 year ago

We decided today that we will formalize an API spec the next time we add to or modify the API, whether for #5104 or for specific extensions of the current API to support an MVP version of securedrop-sdk and the SecureDrop Client.