API design can be a challenging task, especially when dealing with large and complex systems. One of the biggest challenges is ensuring consistency across the different API projects within an organization. When multiple developers work on separate projects, it can be challenging to maintain a unified and consistent approach. Additionally, when changes need to be made to existing APIs, updating all of the APIs that rely on that component can be particularly taxing.
This is where Component Libraries come in. Component Libraries, a newly released feature in Stoplight, helps promote consistency and reuse, allowing developers to create reusable API models and consume them in multiple API projects.
Below, we’ll show you how to use, apply, and socialize this new feature within your Workspace. For more on the value of this new feature, check out this blog or join our webinar on August 3rd.
What are Component Libraries?
A Component Library is a set of reusable models that can be consumed across multiple API projects. By creating these reusable models, you can promote consistency and reduce duplication across their API programs.
This feature allows API program managers to define and publish models, which can then be consumed by other projects rather than having to recreate the same model multiple times. This approach can significantly reduce the amount of time and effort required to create and maintain API projects. You can also update the reusable models in one place, and the changes are immediately available in all the projects that consume the model.
What kind of OpenAPI models should be added to Component Libraries?
Any commonly used and reusable models that can be shared across multiple API projects should be added to Component Libraries. Some examples of OpenAPI models that can be added to Component Libraries include:
- Data models: Models that describe the structure and format of the data used in the API. For example, a customer data model that contains fields like name, email, phone number, etc.
- Authentication models: Models that define the authentication requirements for the API. For example, a JWT authentication model that specifies the token structure and validation requirements.
- Error models: Models that describe the error responses returned by the API. For example, a standard error response model that includes a message, error code, and description.
- Response models: Models that describe the structure of the responses returned by the API. For example, a response model that describes the structure of a product object returned by an e-commerce API.
In general, any models that are used repeatedly in different API projects and can be defined in a reusable way can be added to Component Libraries.
Getting Started with Component Libraries
Creating a Component Library
To create a Component Library, you’ll need to identify the models that should be reused across different API projects. Once you have a list of models, you can create a new Component Library project in Stoplight.
In the Component Library project, you can define and document the models that should be reused. It’s essential to ensure that each model is documented to make it easy for other designers to understand how to use them.
After you have defined and documented your models, you can publish your Component Library. Once your Component Library is published, it is accessible to other developers who can consume the models in their API projects.
Socializing the Component Library
To promote the reuse of the Component Library models, you’ll need to socialize it within your organization. You can do this by sharing the generated documentation with other developers and teams who may be interested in using the models.
Consuming the Component Library models
After you have socialized the Component Library, designers can consume the models in their API projects. When designing an API project, they can add a reference to the Component Library model, and it will be automatically added to the project.
When a model is added to an API project, it is locked for editing. If changes are required, they must be made in the Component Library project, and then the changes can be
pushed to all the API projects that consume the model. This ensures consistency across API projects and eliminates the need for duplicating the same model in multiple projects.
Feedback, Review, and Iteration
As API programs evolve, it’s essential to ensure that the Component Library models are updated accordingly. This includes iterating on existing models and adding new models as needs arise. With the Component Library feature, updates made to a model in the Component Library project automatically result in a notification in all the API projects that consume the model. It’s important to review and accept the updates to ensure that they do not negatively impact the API projects.
The Component Library feature in Stoplight offers can be used in conjunction with Comments and Style Guides as a comprehensive feedback and review system that enables API governance at scale.
In the end, our new Component Libraries Beta feature helps create models, share them, and consume them easily with Component Libraries. You can give it a try for yourself today by logging into your account if you’re on a Pro or Enterprise Workspace. If you have feedback for our Beta, let us know here.
