Ask HN: How would you design a reporting API? How would you research it?
5 comments
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.
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.
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?
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?
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?
Not sure what you mean by a "reporting" API?
Also worth investigating is http://apis.io/ , a growing repository for API interface design patterns.
Find some other systems that behaves similarly to the one you want to build and copy their design.
How would you design this API? Are there any good books or resources covering this?