I’m gearing up for a conversation about the next edition of the FOIA API, and in preparation I’ve created an OpenAPI definition to help guide the conversation, which I drafted based upon the specifications published to Github by the FOIA API team at 18F. This was after spending some time reading through the FOIA recommendations for the project, which is also published to Github. Having the project information available on Github, makes it easy for analysts like me to quickly get up to speed on what is going on, and provide valuable feedback to the team.
In my opinion, EVERY government API should start with a Github repo flushing out the needs and requirements for the project, exactly like 18F is doing as part of their FOIA work. All the details of the project are there for not just the project team, but for external participants like myself. When it comes to engaging with folks like me, the API project team doesn’t have to do anything, except send me a link to the Github repository, and maybe point out some specifics, but if the README is complete, only the repo link is necessary. This opens up conversation around the project using Github Issues, which leaves a history of the discussions that are occurring throughout the project’s life cycle. Any newcomers can invest the time into digesting the documentation, discussion, and then begin to constructively add value to what is already happening.
I know this type of transparent, observable project performance is hard for many folks in government. Hell, it is hard for 18F, and people like myself who do it regularly, by default. It takes a certain fortitude to do things out in the open like this, but this is precisely why you should be doing it. The process injects sunlight into ALL government projects by default. You know your work will be scrutinized from day one, all the way to delivery, so you tend to have your act together. It forces you to open up to other folks ideas and feedback, which isn’t always pleasant, but when done right, can make or break an API project. I mean, your API is going to be public, why not kick it off in the same way? Doing public APIs are all about learning, growing, and establishing a sort of R&D lab around a specific set of resources and services. If this is baked into the DNA of your API project, the chances the API itself will find success is much greater.
I spend a lot of time interfacing with government agencies around APIs. I spend more unpaid time on the phone with folks, and with the right groups I am more than happy to do this. However, I regularly encounter groups who are looking to do APIs, don’t have any existing public APIs, and no Github presence. These are the individuals I encounter who have the worst skills at working well with others, coherently sharing documentation, and many of these projects never get off the ground due to politics. Doing public APIs helps us learn how to be more transparent, observable, and accountable for the projects we are delivering. It isn’t always easy work. It is something that is a journey, and we get better at over time. More government agencies should be working with, and learning from 18F when it comes to delivering projects using Github. Your agency will be better off for it, and the public will benefit from a more observable, and accountable government.
