3 Types of API Fragment Design Strategies

Mary Joy Sabal, MuleSoft Practice Lead at Datacom, is a multi-MuleSoft Certified Developer and Architect and MuleSoft Ambassadress. She frequently speaks at Meetups and is the Wellington Meetup group leader. 

As API developers and architects go about the design process, it is important to be able to discover and share repeatable patterns. This can be easily encapsulated into best practice patterns at the method level (resource types), common traits, and data model (data types). Just as it’s important to have reusable APIs, it’s equally important to have reusable API fragments to make the design and build even quicker and easier.

In this blog, I’ll walk you through the strategies in designing your API fragments, following the REST standards.

What is an API fragment?

The first stage in the lifecycle of an application building block is design. Here, we identify process and business requirements, create logical data models, model API resources, operations/methods, request/response/payload/ codes, etc. which result in API specification.

API fragments are portion of API specifications — they provide 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 critical factors in closing the IT delivery gap.

API fragment design strategies

To speed up designing and creating a RAML specification, I created a new design strategy by building multiple API fragments based on their usage. For example, I had Commons, Security, and Domain fragments. As seen in the image below, the bottom layer contains the API fragments that will be used across all API specifications. The middle layer includes Domain fragments which represent a specific backend system’s common data types and examples that will be used by multiple System APIs integration to a particular domain. The top layer, which is the actual RAML specification, will simply extend the underlying API fragments. Write once, consume everywhere.

Defining reusable API fragments

In this section, I’ll discuss three API fragments that are a part of the design strategies – Commons, Security, and Domain fragments.

Commons fragment

This asset provides a basic set of RAML fragments such as resource types and traits to be used as a common RAML fragment dependency in all API’s to ensure consistency and increased speed of development with regards to RAML specifications.

• Resource types

I’ve categorized it into two sections or parts – collection and member. Collection returns a summary, whereas member returns an object. Within those categories, I group the files based on the method or action.

The following example illustrates a get method that includes a brief display name and description with reserved and custom parameter names as well as corresponding HTTP code and error codes:

• resourcePathName
• getResponseExample
• getResponseType
• errorResponseType
• errorResponseExample

• Common traits

Traits are the smallest reusable component that can define common characteristics across resource methods and resources.They can be a part of the resource (query or URI parameters). In this section, I’ve defined caching, common headers, pagination and rate-limiting traits.

Once we set up resource types and traits, we will encapsulate those in a Library. RAML libraries combine collections of data types, resource types, or traits declarations into reusable groups. It can be applied with the uses node at the root of RAML API definition.

Make the root file of your Commons fragment as a library to expose common resource types and traits. Here, we have a generic collection of reusable RAML resource types and traits particularly useful for RAML beginners.

Securities fragment

This asset provides a generic collection of reusable RAML security schemes particularly useful for RAML beginners.

The following example shows how to set Client-ID enforcement properties:

OAuth 2.0 authentication follows the standard described in RFC6749. The following example shows how to set OAuth 2.0 properties:

Make the root file of the Commons fragment as a library to expose common security schemes to set up on your Mule application.

Domain fragment

For each downstream or back-end service, multiple System APIs can be built in front of it. In line with this, there’s a high possibility to access common data across multiple System APIs that represents a single downstream service. So instead of declaring the data types for each API specification, I’ve introduced a Domain fragment. This contains the common data types and corresponding examples from a single back-end service to be consumed by multiple System APIs.

Similar to the Common and Security fragments, the root file will be declared as a library. This example shows the centralized library of data types for all CRM integrations (CRM as a back-end service).

To make the assets discoverable, we will publish these to Anypoint Exchange — our one-stop shop for connectors, API fragments, template, and other assets.

Building API Specification

Let’s build our main API specification and we will call it CRM Customer System API.

First thing I must do is to import all the required API fragments as dependencies. Here, you could flexibly choose the API fragment version based on your business requirements.

The following example shows how to set up your CRM Customer System API RAML Specification using reusable API fragments.

API fragments allow you to reuse the same system API for the same downstream project. This saves time as developers aren’t starting from scratch.

API definition should be standardized by creating a standard specification of API fragments that maintains long-term consistency. Additionally, it should be consistent by ensuring code reuse when possible by using pattern-driven design.

For more best practices on how to design and manage APIs, download our "How to design and manage APIs" eBook.