When working on a new project and making API design and architecture decisions, the guiding principle for all decisions should really be:
How will customers use it?
As a developer working primarily on the front end of things, I’m interested in answering this question for developing an API to create browser-based UI. We have all used tools and widgets that vary all the way from “raw methods” (no visual changes in the browser) all the way to “full API with configurable parameters” which essentially give you a pre-baked application to tweak. There are also levels in-between. The best browser front-end APIs I’ve used incorporate one or more of the following basic approaches:
Full UI out of the box
Data Interchange API
The conventions for requesting data via (ideally RESTful) URLs are outlined, making it relatively easy to build a web application from the barest element– the data itself. This obviously requires the most work, but has the potential for the tightest integration. Some developers (myself included, if I’m being honest!) prefer to work from the raw data upwards. Understanding the data interchange API and in some cases providing back-end developers with the interchange requirements/template gives them this flexibility.
The main reason for going with only one or two of these options is simplicity. But with good design, a front-end API could easily handle all the above scenarios, giving maximum flexibility (while maintaining simplicity within each scenario) to the developer. There’s no “right” or “wrong” approach except to ensure that the product gives the customers the tools they need.