HN Explorer

Ask HN: How would you design a reporting API? How would you research it?

12 points by georgem12 ↗ HN
I'm trying to design a reporting API for our company (we do real time bidding on advertising). I'm not sure how to structure it and what conventions to use. (for example, there's really nothing to "set" in terms of reporting).

How would you design this API? Are there any good books or resources covering this?

5 comments

[ 3.1 ms ] story [ 30.1 ms ] thread
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?

WorldWideWayne
Find some other systems that behaves similarly to the one you want to build and copy their design.
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/

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