What is an API fragment?
An API fragment is a portion of an API specification, which is why understanding it starts at the API specification level. An API spec consists of a plan of how your API should look structurally – like a blueprint of a house.
The API spec documents what an API does and the expected call and response you can expect from it. It’s a key part of API development because it can help you isolate design flaws or problems before you write a line of code. A way to create APIs more efficiently is to get reuse by reusing portions or fragments of APIs into specs.
Reusable APIs and API fragments are a critical factor in closing the IT delivery gap that arises when there are too many IT projects that need to be delivered with too few IT resources. Instead of starting every project from scratch, you can reuse fragments and APIs to accelerate project delivery.
Let’s imagine you were building a customer API. You’ll notice that some of the snippets or “fragments” of the API spec have a lot of potential for reuse. This can be a security scheme or a data type. For example, a customer data type can consist of first name, last name, and address.
Most likely, the way you describe a customer stays consistent across your APIs, which makes this data type, or fragment, reusable. If you build a library of these fragments, you then have many assets for reuse that can accelerate the speed of building your API spec.
Why reusable APIs and API fragments are so important
Just as it’s important to have reusable APIs available to overcome the constant demand for time-consuming custom point-to-point integrations, it’s equally important to have reusable API fragments to make the design and build of a reusable API even quicker and easier. Then, as you’re building an API, you can save the fragments into a central repository be discovered and used by your colleagues in your organization.
An example of how this might work is the omnichannel API created by the MuleSoft team for the Catalyst Accelerator for Retail, which kickstarts retailers’ digital transformation. This omnichannel API provides methods to support a mobile/web store like product search, shopping cart, customer profiles, etc.
From this one API, our team created 24 fragments of the API spec, including a Customer fragment, an Address fragment, a MapURL fragment, a Shopping Cart fragment…the list goes on and on. Those fragments can be reused in other API specs to create different APIs that serve a different purpose.
Another advantage of building an API spec out of reusable API fragments is that consistency of definitions reduces the effort of implementing APIs. Since “Address” is defined the same way across all APIs, you don’t have to transform that particular function when it’s reused in various services. If you expand that efficiency across all fragments and specs, you eliminate a ton of transformation work, and you, therefore, reduce the time to deliver.