To use Open API specification for adding APIs, separate card description from that of json/yaml file description

[Nazarah]

Problem

Right now, when an API is added to the platform using OpenAPI Specification (uploading json/yaml/ymlfile or providing a link to it), the description field in the API card tries to use the description provided in the specification file.

The character limitation of the description field in API card is 1000.

However, it is general practice to include a description larger than 1000 characters in the swagger or OpenAPI specification files to let users know how the API functions.

So, whenever a valid json, yaml or yml file having a description more than 1000 is attempted to use, Adding API to the platform is not possible.
In any case, the description field in the API card is to give a generalized idea about what the API is for. So the purpose of this description field is different than the description provided in API specification files.

Solutions
After having a chat with @matleppa we suggest the following alternatives:

1. Truncate part of the description provided in open API specification files and add it in the description field for API card.
2. separate the data-schema of description field for API card so that it doesn't take information from the swagger/open API file. API owner can later provide a generalized information about the API after it has been added to the platform.

[matleppa]

Description

I think that the functionality of page [Add API] should be planned again.

Instead of three different ways:

1. fill the form
2. import OpenAPIspec
3. import API configuration

to try to add an API card, there should be only one main line, what to follow.

Problem

In options 2 and 3 the problem is, that in case some content needed in API card is missing, it is not easy for API owner to find out what is wrong.

• is there name for created API card in json/yaml definition?
• is the name duplicate?
• is there URL?
• is the description less than 1000 characters?

In case he/she can figure out the missing or erroneous data, he/she has to edit the original file and reload it in order to be able to try again.
E.g. in case an API card is tried to create by importing a swagger document. Let's say there is an excellent description (so it must be over 1000 chars). Import operation gives an error of too long description.

Let's say the API owner understands, that the description in swagger document needs to be shortened and he/she shortens it and gets an API card created. When looking documentation via API card, he/she finds out, that the previously excellent description is now only a short stump. API owner has to re-write the description and reload the swagger document in order to get it correctly attached on API card documentation.

But what if the swagger document is tried to load from a URL?

In case the API name in API configuration file is a duplicate, API owner has to edit the name in configuration file and load the file again in order to retry.

Proposal

Let's make the way 1 (fill the form) to be the main line. Only that way an API card can be added.

In addition to fill up every input field manually, there would be supportive functionalities

• import OpenAPI documentation
  • imports documentation file and tries to fill fields Name, Description and URL in form based on documentation content.
  • indication, that also openAPI document is to be added with this API card becomes visible
  • the form indicates about missing or erroneous (duplicate name, too long description, erroneous or missing URL) data in input fields
    • API owner can fill missing data or correct erroneous data in form (original file is not altered)
• import API configuration
  • imports file and tries to fill fields Name, Description, URL and Lifecycle based on configuration file content
    • API owner can fill/correct data (original file is not altered)

Either way, when the input fields are correctly filled:

• the API owner presses button [Add API] and the API card is added.
  • in case an openAPI document was also added, it is the original, unchanged version)

[matleppa]

More speculation related to Add APIs matter.

At the moment there is separate pages

• add new API, with fields
  • API Name
  • Description
  • URL
  • Lifecycle status
  • (not so easy to use Import OpenAPI Specification and Import API Configuration)
• Settings in API profile
  • containing among other fields the same four fields as on ADD APIs page
• Proxy in API Profile
  • containing fields related to proxy settings (however, not much explanation to support the API owner)

Why not combine these pages into one?

• With new page all API related setting were in one page, from where they could be altered, wen necessary.
• When a new API is created, the input fields are empty and need to be filled.

The content of page should be refactored such a way, API owner is guided in creating of API. At first is given necessary information and later the less critical info, so that a usable API can be created with minimum effort and filling the information can easily be continued later.

Also more guidance is needed, especially in proxy related part in order to make API owner to be at every step knowing, what he/she is doing.

Perhaps the order of the fields could be something like this:

• minimum (set for creating an API)
  • API Name*
  • URL*
  • Description or Pitch
  • Lifecycle status
    • replace with radio buttons (and good logos for each status)
    • describe, what each status means
    • if production, add also date, till support is given surely
    • if deprecated, add also date for the End
• private/public
  • private by default
• connection to proxy (with explanations)
  • proxy minimum
    • selection of a proxy (in case there are several)
    • API address via proxy (Proxy base path)
      • confirmation in case of change + explanation, that change affects on existing applications
    • API base path + API port
  • proxy advanced (hidden on default, accordion style)
    • Advanced settings (hidden by default, but can be shown by clicking a button)
• API monitoring (API heartbeat)
• connect API to organization
• Authorized users
• logo
• Delete

Lots of guidance and also drawings (even interactive) to show, what is the effect of choices.

• Should there be required information of API owner/updating person?
• SLA?

[Nazarah]

Closing as is resolved by #3324