Onboarding – a challenge and cost in API Management

Posted by cfaurer on April 1st, 2015 filed in Frameworx Consulting, Frameworx Training, REST APIs

How can you keep your support teams from having to answer the same questions all the time about using your APIs? How can you reduce these costs of time and money to your API Management program?

Well, how about providing solid documentation and real-time feedback on how to use your APIs! That’s what AMKB Cloud and Nomos Software have done with the REST APIs specified by the folks at the TM Forum Frameworx API Program, of which AMKB Cloud is an active contributor.

What we’ve done is to use the specification from the TMF Fx API Program as the basis for the documentation of the implementation of the REST API. This includes:

• model generated Business Service Specification
• an API specification that works with Swagger UI
• model generated RuleX business rules in json5 format

The result is an implementation of the TMF Fx REST APIs that provide automated technical support for developers working to use the API 24 hours a day and 7 days a week.

Here’s a snippet from the Customer Management API Specification generated from the AMKB Cloud model of the business service:

From the documentation we can see what’s required to create a valid PaymentMean request dataset as the required attributes and entities are specified. We can also see that there are several business rules defined for the BankAccount entity.

The model represented in the document snippet shown above is the source used to generate the swagger.json file that drives the Swagger UI shown here:

The  swagger.json that is driving the Swagger UI is shown here:

If you look closely at the swagger.json specification you will see that it matches what was defined in the business service specification doc, as expected.

The last piece needed is the RuleX json5 file generated from the model of the API:

The swagger.json and customerManagementRules.json5 files generated from the AMKB Cloud model of the business service are the required inputs to the Nomos Software RuleX validator and result in a  customerManagement.war that is deployed to a rules server. The RuleX war is called by the Reference Implementation (RI) of the REST API (to learn more about how this is done visit – TMF Fx & Nomos RuleX, Cameo E2E Builder/Server – Part 5)

Let’s try out the AMKB Cloud RI of the Customer Management REST API with Nomos Software RuleX validation.

Notice that the Swagger UI is using the swagger.json generate from the model and that the default values set in the model are driving the user interface.

And the response of the create request shows that the new PaymentMean has been created behind the API:

So, by default a valid create PaymentMean dataset is provided by the Swagger UI being driven by the model, specification and swagger.json. What if we make a mistake? What happens then? Let’s change the PaymentMean type from DD, which stands for Direct Debit, to Credit and see what happens:

You may have noticed that there are 25 business rules defined for the Customer Management API and they provide feedback similar to what’s shown above. What went wrong and where.

So, what can be done to reduce the time and money spent supporting API Management?

Give us a call and let’s talk about how we can help. 

Name: *

Email Address: *

Subject: *

Message: *

− 2 = one