This blog marks the final part of our mini blog series, focusing on the significance of the Open API Spec framework for BTP CAPM API and microservices.
Let's recap the series: In Part 1, we discussed the importance of understanding OpenAPI specification documentation. In Part 2, we explored how it can be easily implemented in CAP services using the Node.js build pack.
In this concluding blog, we will showcase practical examples of using different annotations in real-world scenarios. We'll see how the Open API framework seamlessly incorporates these annotations, enabling smooth collaboration among multiple teams during the API development process.
How Annotations Play a Major Role in API Documentation
The diagram presented above illustrates the technical development flow for API development. The process begins with CDS modeling, where the foundation for CAPM services is established on top of the CDS model.
To enhance the metadata associated with the development process, annotations play a vital role.
These annotations are employed to provide additional information and enrich the metadata, ensuring a more comprehensive understanding of the API and its functionalities.
Important Note: I'd like to emphasize a key point here. Annotations are a broader concept, but their impact on Open API spec generation is significant. By leveraging annotations, APIs become more expressive and communication between teams becomes easier.
"Annotations play a vital role in enhancing collaboration and fostering effective API development."
Let's Start :
we will explore the practical application of different annotations to enhance various aspects of API development. We will focus on the following areas:
1. Query Operations: Enhancing data retrieval with efficient annotations.
2. Navigations on Entities: Streamlining access to related data through targeted annotations.
3. Validations: Ensuring data integrity with annotated validation rules.
4. Authorizations: Fine-grained access control through powerful annotation-based authorization.
5. Entities Behavior (Read, Update, Delete): Defining entity behavior effortlessly with annotations.
Where we stand now( Part 2) without Annotations:
In Part 2 of the series, we established the Data Model and its associations. Building upon this foundation, we will now delve into the realm of annotations, exploring their capabilities and observing the corresponding responses they generate.
Real World Requirements & Scenarios , Problem Statement:
Above the API documentation diagram reveals that all endpoints support various operations such as GET, PUT, POST, DELETE, and Query Operations. However, this approach does not align with the ideal real-world scenarios. Each endpoint should exhibit distinct behavior based on the user's access level and the corresponding business logic.
To address this challenge, annotations helps to define the behavior and query operations associated with different endpoints.
Problem Statement 1 :
Say I have developed the Purchase Order End Point for the Below scenarios hence it Should reflect in Open API Spec:
1. Purchaser Order can be retrieved with Top
2. Purchase Order Skip is not Supported.
3. Purchase order Count can't retrieved.
4. Purchase Order can not be Updated ,.
5 Purchase Order can not be Deleted.
Let's Implement Solutions with power of Annotations
Now, Lets see the Open API Spec and observes the response.
Problem Statement 2
Say I have developed the Business Partner End Point for the Below scenarios hence it Should reflect in Open API Spec:
Let's Implement Solutions with power of Annotations
Now, Lets see the Open API Spec and observes the response.
Problem Statement 2
Say I have developed the Product for the Below scenarios hence it Should reflect in Open API Spec:
Let's Implement Solutions with power of Annotations
Now, Lets see the Open API Spec and observes the response.
We have delved into numerous annotations across various real-world scenarios and observed firsthand how the Open API Spec effortlessly represents these capabilities. This brings immense benefits in terms of maintaining a strong governance model, facilitating efficient collaboration, and boosting development efficiency.
I trust that you have found this blog series enjoyable and informative. If you have any further questions or would like to connect, please don't hesitate to reach out to me on LinkedIn.
I encourage you to continue exploring the vast range of annotations and capabilities that can be offered by the framework. There is much more to discover and leverage for enhancing your development journey.
#KeepExploring#KeepSharing#KeepGrowing
Cheers:
Mohit Bansal
Let's recap the series: In Part 1, we discussed the importance of understanding OpenAPI specification documentation. In Part 2, we explored how it can be easily implemented in CAP services using the Node.js build pack.
CAPM Open API Framework |
|---|
Part 1 – Empowering SAP BTP CAP Services through Open API Spec and Annotations for Effective Communi...\ Agenda : Recognize the Significance of Standardized and Consistent API Documentation for the CAPM Service |
Part 2 – Empowering SAP BTP CAP Services through Open API Spec and Annotations for Effective Communi... Agenda : CAPM Open API Documentation: Implementation and Development Approach |
Part 3 – Empowering SAP BTP CAP Services through Open API Spec and Annotations for Effective Communi... Agenda: Let’s take a deep dive with annotations & elevate CAPM API documentation to the next level. |
In this concluding blog, we will showcase practical examples of using different annotations in real-world scenarios. We'll see how the Open API framework seamlessly incorporates these annotations, enabling smooth collaboration among multiple teams during the API development process.
How Annotations Play a Major Role in API Documentation
Technical Development Process Flow, Power of Annotations
The diagram presented above illustrates the technical development flow for API development. The process begins with CDS modeling, where the foundation for CAPM services is established on top of the CDS model.
To enhance the metadata associated with the development process, annotations play a vital role.
These annotations are employed to provide additional information and enrich the metadata, ensuring a more comprehensive understanding of the API and its functionalities.
Important Note: I'd like to emphasize a key point here. Annotations are a broader concept, but their impact on Open API spec generation is significant. By leveraging annotations, APIs become more expressive and communication between teams becomes easier.
"Annotations play a vital role in enhancing collaboration and fostering effective API development."
Let's Start :
we will explore the practical application of different annotations to enhance various aspects of API development. We will focus on the following areas:
1. Query Operations: Enhancing data retrieval with efficient annotations.
2. Navigations on Entities: Streamlining access to related data through targeted annotations.
3. Validations: Ensuring data integrity with annotated validation rules.
4. Authorizations: Fine-grained access control through powerful annotation-based authorization.
5. Entities Behavior (Read, Update, Delete): Defining entity behavior effortlessly with annotations.
Where we stand now( Part 2) without Annotations:
In Part 2 of the series, we established the Data Model and its associations. Building upon this foundation, we will now delve into the realm of annotations, exploring their capabilities and observing the corresponding responses they generate.
Open API Spec Initially without Annotations
Real World Requirements & Scenarios , Problem Statement:
Above the API documentation diagram reveals that all endpoints support various operations such as GET, PUT, POST, DELETE, and Query Operations. However, this approach does not align with the ideal real-world scenarios. Each endpoint should exhibit distinct behavior based on the user's access level and the corresponding business logic.
To address this challenge, annotations helps to define the behavior and query operations associated with different endpoints.
Problem Statement 1 :
Say I have developed the Purchase Order End Point for the Below scenarios hence it Should reflect in Open API Spec:
1. Purchaser Order can be retrieved with Top
2. Purchase Order Skip is not Supported.
3. Purchase order Count can't retrieved.
4. Purchase Order can not be Updated ,.
5 Purchase Order can not be Deleted.
Let's Implement Solutions with power of Annotations
@Capabilities: {
TopSupported : true, // Requirement 1
SkipSupported: false , // Requirement 2
CountRestrictions : { // Requirement 3
Countable : false
},
UpdateRestrictions : { // Requirement 4
Updatable : false
},
DeleteRestrictions : { // Requirement 5
Deletable : false
}
}
entity Purchaseorder : cuid {
PurchaseOrder : String(24);
Businesspartner_Guid : Association to Businesspartner;
Amount : Amount;
Status : String(1);
Items : Composition of many PurchaseOrderItems
on Items.PurchaseOrder = $self;
Note : String(255)
}Now, Lets see the Open API Spec and observes the response.
Scenarios 1 and Response in Open API Spec
Problem Statement 2
Say I have developed the Business Partner End Point for the Below scenarios hence it Should reflect in Open API Spec:
- Business Partner Mobile Number is Mandatory to read the Filter.
- Business Partner all fields should be retrieved, Not able to select only one field.
- Business Partner response must not be sorted by Company.
- No Search is allowed on Business Partner.
- BP should not allowed to create / Update / Delete.
Let's Implement Solutions with power of Annotations
@Capabilities : {
FilterRestrictions : //Requirement 1
{
RequiredProperties : [MobileNumber]
},
SelectSupport : // Requirement 2
{
Supported : false
},
SortRestrictions : //Requirement 3
{
NonSortableProperties :[CompanyName]
},
SearchRestrictions : //Requirement 4
{
Searchable : false
},
InsertRestrictions : { //Requirement 5
Insertable : false
},
UpdateRestrictions : {
Updatable : false
},
DeleteRestrictions : {
Deletable: false
},
}
entity Businesspartner {
key BusinesspartnerGuid : Guid;
BP_Role : String(2);
Email : String(64);
MobileNumber : String(14);
AdressGuid : Association to Address;
BP_ID : String(16);
CompanyName : String(80);Now, Lets see the Open API Spec and observes the response.
Scenario 2 : Playing with Annotation and Response in Open API Spec
Problem Statement 2
Say I have developed the Product for the Below scenarios hence it Should reflect in Open API Spec:
- Product can be read only with Product ID.
- Generic Product reading ( Products entity set ) is not allowed.
- No Navigation from Products to Business Partner.
Let's Implement Solutions with power of Annotations
@Capabilities: {
ReadRestrictions : {
Readable : false, // Requirement 1
ReadByKeyRestrictions: // Requirement 2
{Readable: true
}
},
NavigationRestrictions: {RestrictedProperties: [{ // Requiement 3
NavigationProperty: SupplierGUid,
ReadRestrictions : {Readable: false
}
}]
},
}
entity Product {
key ProductGuid : Guid;
ProductID : String(28);
ProductType : String(2);
Category : String(32);
Description : localized String(255);
SupplierGUid : Association to Businesspartner;
Price : Amount;
}Now, Lets see the Open API Spec and observes the response.
Scenario 3: Play with Annotations and Open API Spec
We have delved into numerous annotations across various real-world scenarios and observed firsthand how the Open API Spec effortlessly represents these capabilities. This brings immense benefits in terms of maintaining a strong governance model, facilitating efficient collaboration, and boosting development efficiency.
I trust that you have found this blog series enjoyable and informative. If you have any further questions or would like to connect, please don't hesitate to reach out to me on LinkedIn.
I encourage you to continue exploring the vast range of annotations and capabilities that can be offered by the framework. There is much more to discover and leverage for enhancing your development journey.
#KeepExploring#KeepSharing#KeepGrowing
Cheers:
Mohit Bansal
- SAP Managed Tags:
