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

[georgem12]

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?

[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.

[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

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

[dtsingletary]

Also worth investigating is 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.