
Ask HN: How would you design a reporting API? How would you research it? - georgem12
I&#x27;m trying to design a reporting API for our company (we do real time bidding on advertising). I&#x27;m not sure how to structure it and what conventions to use. (for example, there&#x27;s really nothing to &quot;set&quot; in terms of reporting).<p>How would you design this API? Are there any good books or resources covering this?
======
smt88
Good APIs are like good code. You don't want to get creative. Instead, you
want the API to be usable by being immediately familiar. Follow the lead of
popular, well-designed APIs (Parse and Twilio come to mind). You should follow
a predictable pattern, which minimizes the amount of time required to learn
your API. For example, if your endpoints are in the "/[noun]/[verb].json"
scheme, then you should stick to that all the way through.

I suggest starting out by strictly adhering to REST standards, and then choose
areas where you want to be flexible to increase usability (allowing POST calls
to be overridden and interpreted as PUT calls, for example).

Check out this checklist: [https://mathieu.fenniak.net/the-api-
checklist/](https://mathieu.fenniak.net/the-api-checklist/)

I can also enthusiastically recommend Apiary
([https://apiary.io](https://apiary.io)) for designing and mocking up your
API. It's absolutely fantastic.

------
me_bx
Could you elaborate a bit more?

By reporting API, do you mean a structured way for some users/clients to
extract operational data about their activity with your product, in order to
let them play with it and do their own reporting on top of it? Or do you mean
a layer in your software presenting aggregated data in form or reports?

------
petervandijck
To design an API, there are a few good ebooks, well worth the price:
[https://leanpub.com/build-apis-you-wont-hate](https://leanpub.com/build-apis-
you-wont-hate)

Not sure what you mean by a "reporting" API?

------
dtsingletary
Also worth investigating is [http://apis.io/](http://apis.io/) , a growing
repository for API interface design patterns.

------
WorldWideWayne
Find some other systems that behaves similarly to the one you want to build
and copy their design.

