Singluar vs. Plural Nouns

[acurley]

First off, love the documentation and great work you have done throughout the Federal space on designing and implementing APIs.

I'm trying to follow your best practices, both encapsulated in this README and your API work in the wild but I'm having difficulty understanding your choice for using singular and plural nouns in the FEC Open API. Throughout the API you use /candidate, /candidates, etc.. and it is clear that /candidates is intended to return an array of objects while /candidate is intended to return one.

This practice is curious. As a Rails person I am used to plurals are all over the place in the API (even when intended to pull one record like the route /users/1). I was wondering if you could document in this README your reasoning for mixing singular and plurals.

[LindsayYoung]

Hi, thanks for reaching out! There are a few anti-patterns in the FEC API. That is because we use it in our production system and make optimizations for beta.fec.gov. Most endpoints have a lot of documentation, so I hope that makes things easier for our users, there is a lot to take in.

To your specific question, we use singe nouns when one thing is returned and plural nouns when multiple things are returned. The development patterns are to optimize for the website. For example we had all the information in candidates in /candidates and it was intolerably slow. Getting quick calls to filter through large lists of people and things and then later we do calls for more in-depth results, when you are looking for a particular candidate, committee etc. Then you can see things like the pertinent committee details that are related to a candidate. That information is important but bogs things down. We also tried to make a lot of api cals by breaking the different types of information into smaller buckets and that was too slow as well.

Another thing that is sub optimal, is the 2 kinds of pagination. We built this iteratively and realized several months in that we couldn't use page= for the largest data sets and had to use approximate counts, again they were intolerably slow. We would like a unified pagination in the future, but don't want to make breaking changes without warning and a transition plan, since this is a public API that people use.

There are a few other clean up tasks we would like to do in the future as well. We always aspire to make the API even better.