LinkedIn
Twitter
How you design your APIs has big impacts across your digital value chain. Meeting your adoption or sales goals, reducing costs across lines of business, speeding up time to market, and time spent supporting your customers are all goals within easy reach when an API is easy to use. And easy-to-use APIs are almost always designed from the outside-in.
When many of us start designing our first APIs, we tend to approach it from an “exposure” model: taking our data and exposing it to our partners or customers. At its simplest this approach is little more than a RESTful wrapper for existing database tables or outdated soap services. The problem is this can quickly lead to APIs that are chatty (too many API calls for a simple result), bloated (excessive amount of data), or confusing (requiring insider understanding of your business logic)
Under an outside-in paradigm, the API design is built around the consumers' use cases for the data rather than the structure of the data in your system. The notion of outside-in thinking should be familiar to Product Managers, who routinely have to demonstrate customer empathy and put themselves in their customers' shoes. If your team has a Product Owner, be sure they are empowered to decide on what functionality is needed from the API. This should be the driving force of your design
Here some other ways to approach successful outside-in design.
Think About Customer Use Cases
What are your customers likely to build with your APIs? Will it be apps? Dashboards? Workflow integrations? Monitoring and alerting?
The best way to learn what your customers want is to ask them. Look at their apps, ask about their pain points, discover where your APIs can streamline or simplify your customers' lives. Maybe they are building a mobile interface that needs data from several systems; or they want to create a one-button sync that automagically handles a complex workflow. Create sample API responses that give them exactly the data they need. It doesn't matter where the data comes from in your system; pretend you're building the system from scratch.
You may find a lot of overlap between the payloads, with minor variations here and there. Adapt your designs as necessary to genericize them across common or similar use cases. Try to hit as many birds with one stone as you can.
Another approach is more imaginative. Sometimes you might not have direct access to your customers, they don't have time, or they don't know what they want. In these cases and in addition to the above, think about what you would build with your APIs. Think big. Think creatively. While you don't want to design your APIs for vaporware, thinking about the big picture can make it easier to build non-breaking changes in the future.
Assume Zero Knowledge of Your Business Logic
As systems of record evolve, they can become a web of interconnected dependencies and highly branched decision trees. You need to hide all of that when it comes to your APIs. Your customers do not have time to learn the inner workings of your system and they never should need to: they simply want the data they need to enrich their own application.
Occasionally a workflow will require multiple API calls, and that's okay, but make the call chain as simple as possible and provide clear documentation. To test your API design’s simplicity, pretend you are building the whole system from scratch. If you encounter an inefficient workflow and say to yourself, "Well it has to be this way because of <system complexity issue>," then keep trying to refactor.
Reduce the Number of API Calls
Outside-In design could easily be summarized as: Simplify. Look for ways to reduce the number of API calls a customer must make in their application's workflow. If your consumers are building mobile applications they have to be careful about battery drain; requiring a couple of calls instead of a dozen can make a big difference.
There is a fine balance between building distinct, data-driven microservices and streamlining API usage. You may want to consider offering both: fine-grained APIs for specific data types, and experience APIs around common or even customer-specific user interfaces. These “Experience APIs” composite multiple smaller domains into a single endpoint; making it much simpler for your customers—especially those building user interfaces—to render their screens easily and quickly.
Allow Flexibility
In following the first couple of steps above, you may find you have beautifully designed payloads that elegantly cover a variety of use cases in just a few endpoints. There are always edge cases and unique customer needs; once you have your base designs, start adding options to make the endpoints more flexible. Options here include:
Filtering Out Response Properties
Build the ability for customers to request only the properties they need. If you were building an API for books, you may include every bit of data about a book; but if one of your customers only needs the title, author, and bestseller ranking, give them the ability to retrieve only that data with a query string parameter. A common way of doing this looks like:
GET /books?properties=title,author,ranking
Sorting and Pagination
Generally, you don't want to guarantee the order of objects in an API response, because minor changes in logic or peculiarities in your data source might change the sort order at some point. But in some cases, your customers may want to sort by a particular field. Giving them that option, combined with pagination option which can also improve performance, will give them a highly efficient API when they only want the top few results.
On-the-Fly Composites
Occasionally, you may have APIs that are related, but should remain taxonomically distinct. For example, you may have the Books API above, and a separate Author Profile API. Customers may want this data individually, or they may want all of it in one API call. Like an Experience API, on-the-fly composites give your customers the option to build their own data combinations. This dynamic and flexible approach can even eliminate the need for building experience APIs in the first place.
One design pattern you might employ is the expand query string parameter. For example, if the Books API included authorId as a parameter, you could offer the option to send:
GET /books/123?expand=author
which would include the result of a second API call:
GET /authors/smith-john
Build Human-Readable Designs
While APIs are meant for computer-to-computer interaction, the first client of an API is always a human, and the API contract is the first piece of documentation. Developers are more apt to study your URI and payload design before they dig into your docs, so eliminate any ambiguity in property names. If any of those labels could be interpreted in more than one way, adjust them to be more clear.
For example, if you include a property named "restrictions" that contains restriction exemptions, then the property name should probably be restrictionExemptions. A few extra bytes in the payload can save a lot of early confusion and accelerate adoption of your API.
Pursue Practical—Not Perfect—REST
RESTful API design can spark some spirited debates, but the most important thing to remember is that your customers are just trying to get their job done. They want an API that works and makes sense. Being as true to the RESTful basics—such as using the correct HTTP verbs, status codes, stateless resource-based interfaces—makes your customers' lives easier. But don't die on hills like versioning or perfectly using HTTP headers.
Your goal should be helping your customers be successful with your data, as quickly and easily as possible. Occasionally that may mean breaking some "rules" of REST in order to offer simpler and elegant interfaces. Simply be consistent in your design choices across all of your APIs, and be very clear in your documentation about anything that might be peculiar or nonstandard.
