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
The product ships as a fully fleshed-out component or application out of the box, including all the HTML, JavaScript, and CSS to make it not only work but look good. With a few basic configuration changes, the component or application should be pretty much “ready to go”. Anything more than this, and the development approach is really in what I think of as the next level:
HTML API
The documentation describes HTML conventions that the JavaScript layer will “see” and populate with UI components. This allows the developer to use their own layout engine (whether developed in-house or borrowed from popular frameworks), select which components are visible, and where on the page. As with the “Full UI” approach (and really, any web development task in general), the developer is free to customize CSS to achieve corporate look and feel and seamlessly integrate the client within their application.
JavaScript and Data Interchange API
At the end of the day, every component is simply a way to expose data interchange. The JavaScript API allows the developer to access these methods via pre-composed JavaScript methods that make the appropriate requests for data from a given source (whether that source is in-memory or from a remote source). Methods can return optional pre-composed HTML that can be injected into the DOM, or simply return data (for example, the status of an ongoing process) in a usable format such as JSON, which can then be handed off to additional JavaScript methods developed in-house to process and render the data.
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.
