Part 3 – Empowering SAP BTP CAP Services through Open API Spec and Annotations for Effective Communication, Collaboration and Governance

[mohit_bansal3]

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.

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:

1. Business Partner Mobile Number is Mandatory to read the Filter.


2. Business Partner all fields should be retrieved, Not able to select only one field.


3. Business Partner response must not be sorted by Company.


4. No Search is allowed on Business Partner.


5. 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:

1. Product can be read only with Product ID.


2. Generic Product reading ( Products entity set ) is not allowed.


3. 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