How to Ensure API Reusability – Keeping A Product Mindset for API Design

Ron Reed, Director of Strategic Services

You may be using MuleSoft Anypoint platform as a project accelerator but how are you ensuring reusability of the APIs you are building?

We have all been there; if we just had a bit more time we could really make this feature solve more problems than just this one…but the reality is projects have a scope, budget, and time. These elements of a project usually pull at one another, create friction and ultimately force tough decisions. 

The MuleSoft Anypoint platform complements an API-led design approach and promotes reuse as one of its key benefits. In order to tap into that benefit, you need to ensure you are having a product mindset when designing your APIs even when those APIs are being created for a specific project. Even when scope, budget, and time are pulling against you the following three tips will help you keep a product mindset when designing an API to deliver to a project’s requirements.

Create A Control Use Case

Enable the technical team to think beyond an initial project’s implementation by working with the product team or stakeholder to create a tightly constrained scenario that the API design team can bounce potential scenarios against to ensure some level of reusability. The scenario should be based on future functionality that the product team believes will need to be addressed for a new audience. This is by no means scope creeping your project, but instead gives you another vantage point while designing the API. It will help drive more ownership of the APIs within your organization as it is designed for more use beyond a single project use case.

Let’s take an example for an eCommerce site where you are creating APIs to unlock better order management tracking capabilities for a refreshed site or new mobile app experience. What about considering giving access to these capabilities to your customer service team? As you are decomposing the requirements for the new customer experience, you could validate your approach on whether a Process API should be used or not. Or you could check the level of search capabilities that may be needed to be exposed from a System API. 

One other tip when picking a control use case, it is always helpful using a scenario that is for internal process enablement – the user base is a bit more well known. The idea here is to avoid endless what-if analysis on what the API could be and instead focus on what it should be for your project and at least one other iteration.

Speak Your Language

Turning legacy and third-party information into a language your company speaks now is a form of enablement that can be lost when challenged with project timelines. Taking the time to do so in your project will pay dividends for your organization. Work with the product team to create business entities that the technical team can emulate in their model. Creating entity relationships can help a development team ensure that consistency is honored between different API layers. Beyond the entities, the data itself needs an area of focus to bring the voice of your organization and avoid letting other systems’ naming conventions creep into your APIs. Any analyst knows the “fun” of data mapping exercises but beyond just mapping – really take a look at how you are identifying the information within your own organization. Traditional point-to-point integrations have an input and an output that you need to connect. Challenge yourself to add one additional column to the middle of that mapping for what your organization calls it and have that be the language spoken in your internal API application network.

A simple example of the zip code, you may have a legacy system that just says ”Zip“ and another new third party that calls it ”Postal Code“ but what does your organization call it? Find out and make that a consistent approach for your lower-level APIs. Let the Experience APIs be the place to deviate but your Process and System APIs need to be in your organization’s language.

Celebrate Your APIs

As companies scale and teams become more remote, information tends to suffer. Within Anypoint Exchange, discovery and publishing of API information is centralized in the same place to ensure you have all your APIs at your fingertips. But these APIs are only as good as the documentation that comes with it. Have you ever started out a project and were told that this integration was built by another team last year? You hunt through documents created from past project teams to hopefully find something that informs you of exactly what they integrated with and no clue what is accurate. 

Once your project is complete, take the time to document your API in a way that others can tell what that API is doing, where the data is coming from and what the expectations are so they can build their solution by leveraging your hard work. Not to mention, make sure you take a peak before you go and build your own API. I probably should have mentioned that earlier…

Take the steps to think beyond your project and create a more product-focused API, then celebrate your success by giving the API more weight within Exchange by adding details on how to use it and some working examples. Promote the use of your API by giving others guidance on what this API can do and what it could do. Let others be creative with the APIs you create.

Summary

Hitting a project deadline is never easy. These tips are to aid in the discussion, design, and documentation of APIs; they are not meant to add complex requirements to your projects. In order to adopt an API-led approach and maximize the benefits of MuleSoft, you need to spend more time in your API design. By taking the time to test your design against another use case, translate the data, and create meaningful documentation you will unlock more reuse potential out of your project delivery. With the MuleSoft platform being a development accelerator, hopefully, you and your team can use that additional time to focus on creating a more product-minded API.