API Connect

 View Only
  • 1.  Creating API defination for clients

    Posted Sun January 27, 2019 11:39 AM
    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.


    Susant Kumar Palai

  • 2.  RE: Creating API defination for clients
    Best Answer

    Posted Mon January 28, 2019 09:46 AM
    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.

    IBM Champion - Cloud 2019

  • 3.  RE: Creating API defination for clients

    Posted Tue January 29, 2019 03:43 PM
    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