Background
Libraries provide the ability to define, share, and reuse pre-defined sets of datatypes, resource types, traits, security schemas and reusable assets all in the namespaced environments.
An API fragment is a RAML document that has a version and an identifier but is not by itself a complete RAML specification. An API fragment is one of the following types. It is defined by RAML specification for descriptions of the types.
- Trait
- Resource Type
- Library
- User Documentation
- Example
- Security Scheme
- Trait
- Type
In this article, we shall describe the steps to define Library, Traits, Resource Types and published to API Exchange, including creation of API specification creation and publication.
Usage of fragments through exchange helps in reusability across multiple projects and across the enterprise.
Steps
Creation Of API Fragment – Library
- Log into Anypoint Platform and go to Design Center
- To create a new project, click Create New > New Fragment > Select “Library” under Fragment Type, provide a Fragment Name and click Create Fragment.
- Screenshot below
- Define a “type” named Customer. Assign the needed properties to “Customer”, based on the business object requirements. In this example, a few properties are assigned to “Customer” that is being defined for use across multiple projects. Screenshot below.
Creation Of API Fragment – Trait
Traits is like a function and is used to define common attributes for http methods (GET, POST, PATCH, etc.). Traits can be declared in the same raml file as the API specification or it can be defined in a new file.
Consider an example. Error Responses Trait to implement error messages and error codes.
- To create a Trait, click Create New > New Fragment > Select “Traits” under Fragment Type, provide a Name and click Create Fragment.
- Define the needed “Traits” for the application
- Screenshot below
Creation Of API Fragment -Resource Type
Resource type is basically a template that is used to define the descriptions, methods, and parameters that can be used by multiple resources to avoid duplicates. Declaring resource types using http methods like GET and POST.
Consider an example. employee resource has to implement GET and POST methods. Each http method will have responses, description, etc.
- To create a Resource type, click Create New > New Fragment > Select “Resource Type” under Fragment Type, provide a Name and click Create Fragment.
- Defining http methods post and get method response type and description.
- Screenshot below
Publish Common Library To Exchange
The next step in the process is to publish the Library to Exchange. This is performed through the steps below.
- From the previous step, look for “Publish” at the top-right corner that is used to publish the fragment to Anypoint Exchange.
- Click the Publish button.
- Specify a version number, then click “Publish to Exchange”
- Screenshot below
- When the API fragment is published on the Exchange, it appears on the API portal for the enterprise.
- In the Exchange, customer library portal created. It is now available for reference from other API specification projects or can also be downloaded and imported into API Specifications offline.
Publish Traits To Exchange
The next step in the process is to publish the Traits to Exchange. This is performed through the steps below.
- Publish to API Exchange by clicking on top-right corner of the text editor.
- When the API fragment (trait) is published on the Exchange, it appears on the API portal for the enterprise.
- In the Exchange, trait is created. It is now available for reference from other API specification projects or can also be downloaded and imported into API Specifications offline.
- Screenshot below
Publish Resource Types To Exchange
- Publish to Exchange by clicking on top-right corner of the text editor.
- When the API fragment (Resource Type) is published on the Exchange, it appears on the API portal for the enterprise.
Import Common Library From Exchange Into An API Specification
The next steps showcase how a library that is available in Exchange can be utilized as part of an API Specification in Anypoint Design Center.
- Go to the API Specification where the common library needs to be referenced from
- Click the drop down in the top-right corner of the text editor and select “Import from Exchange” and select the asset (common library)
- After the import is complete, the common library becomes a part of the API Specification. This specification can be imported into Anypoint studio for implementing the services.
- Screenshot below
Import Traits From Exchange Into An API Specification
- Go to API Specification where the Traits needs to be referenced from
- In the API specification get the dependencies by clicking on add dependencies in the left side of the text editor
Import Resource Types From Exchange Into An API Specification
- Go to the API Specification where the resource type needs to be referenced from
- In the API specification get the dependencies by clicking on add dependencies in the left side of the text editor
Use Imported Artifacts For Library, Trait And Resource Type
- To use imported Library in the project using “uses” keyword and give the root as customerLibrary.raml as shown below screenshot
- Imported traits can be referred in the API Specification by using the “is” keyword.
- Imported resource types should be referred in the API Specification by using the “type” keyword.
Testing API Specification
- Use the Toggle button to enable testing the Mocking service
- To test, use the HTTP method (GET, POST, etc.) and click on “Try it”
- After clicking on “Try it”, click on the “Send” button to invoke the appropriate operation (GET, POST, etc.).
- The appropriate response message is returned
Conclusion
This article showcased the use of a common artifacts for library, trait and resource types by creating appropriate fragments. The library contained business object “Customer”, the trait contained “Error Response”, and Resource Type contained a business object “Employee”. This fragment was published onto the Exchange, and an API specification imported this by leveraging the reusable nature of the published common library on the Exchange.
By defining common types as libraries and publishing them to Anypoint Exchange, it becomes easy for enterprise-wide reusability and reduces duplication of work.
