API Connect

Hi All,
I understand that in general API consumers can log in to Developer portal to check out the definition for the available API's which includes parameter level details, description sample request , response format etc. This all is applicable provided parameter level details have been provided while creating an API.
Now consider the case , where I am just creating a Proxy API for the existing back end service. In this case i will not be defining any request response parameters in my API .
So for this case my consume will  not be able to see the parameter level detail or complete request response details for the API.
How do we handle such cases ? Is there a way to convert the back end WADL or WSDL file to some other format , may be Swagger format so as to make the complete back end service details  available on Developer Portal .
What is the industry practice we follow for such cases.

Regards
Susant

------------------------------
Susant Kumar Palai
------------------------------

There is no easy/correct answer here and one we discuss often. It is a balance between having a fully documented API in the Developer Portal versus the effort it is to create (and maintain) this documentation.

I think that with a SOAP APIs it is a bit easier, as you can just import the WSDL into APIC and then it will generate all of the request/response objects for you, and you would want to keep the exposed WSDL up to date so that you can validate requests prior to letting them into your data network. For REST services it is more difficult unless your backend service can create (or be converted into) Swagger 2.0 (OpenAPI.) Otherwise you will need to "manually" create all of the  *Definitions* so that the DevPortal documentation is correct.

While it is always dependant on the business drivers, if you are investing in an API management solution, you more than likely believe in the two speeds of IT, or the loose coupling of your external contracts to your internal contracts and thus the time/effort to create and maintain this documentation would be worth it.

------------------------------
Devin
IBM Champion - Cloud 2019
------------------------------

Original Message:
Sent: 01-27-2019 11:39 AM
From: Susant Kumar Palai
Subject: Creating API defination for clients

Hi All,
I understand that in general API consumers can log in to Developer portal to check out the definition for the available API's which includes parameter level details, description sample request , response format etc. This all is applicable provided parameter level details have been provided while creating an API.
Now consider the case , where I am just creating a Proxy API for the existing back end service. In this case i will not be defining any request response parameters in my API .
So for this case my consume will  not be able to see the parameter level detail or complete request response details for the API.
How do we handle such cases ? Is there a way to convert the back end WADL or WSDL file to some other format , may be Swagger format so as to make the complete back end service details  available on Developer Portal .
What is the industry practice we follow for such cases.

Regards
Susant

------------------------------
Susant Kumar Palai
------------------------------

Thanks for the detailed information Devin.
I will try to add it manually in the definition so as t make it available in YAML file and will not use it in Assemble.

------------------------------
Susant Kumar Palai
------------------------------

Original Message:
Sent: 01-28-2019 09:46 AM
From: Devin Richards
Subject: Creating API defination for clients

There is no easy/correct answer here and one we discuss often. It is a balance between having a fully documented API in the Developer Portal versus the effort it is to create (and maintain) this documentation.

I think that with a SOAP APIs it is a bit easier, as you can just import the WSDL into APIC and then it will generate all of the request/response objects for you, and you would want to keep the exposed WSDL up to date so that you can validate requests prior to letting them into your data network. For REST services it is more difficult unless your backend service can create (or be converted into) Swagger 2.0 (OpenAPI.) Otherwise you will need to "manually" create all of the  *Definitions* so that the DevPortal documentation is correct.

While it is always dependant on the business drivers, if you are investing in an API management solution, you more than likely believe in the two speeds of IT, or the loose coupling of your external contracts to your internal contracts and thus the time/effort to create and maintain this documentation would be worth it.

------------------------------
Devin
IBM Champion - Cloud 2019

Original Message:
Sent: 01-27-2019 11:39 AM
From: Susant Kumar Palai
Subject: Creating API defination for clients

Hi All,
I understand that in general API consumers can log in to Developer portal to check out the definition for the available API's which includes parameter level details, description sample request , response format etc. This all is applicable provided parameter level details have been provided while creating an API.
Now consider the case , where I am just creating a Proxy API for the existing back end service. In this case i will not be defining any request response parameters in my API .
So for this case my consume will  not be able to see the parameter level detail or complete request response details for the API.
How do we handle such cases ? Is there a way to convert the back end WADL or WSDL file to some other format , may be Swagger format so as to make the complete back end service details  available on Developer Portal .
What is the industry practice we follow for such cases.

Regards
Susant

------------------------------
Susant Kumar Palai
------------------------------