APInf APIs, Organizations, Users API design changes

[bajiat]

Current version of the APInf Catalog API design specification is in Swaggerhub. There was a comment round for community about the specificatin, but the changes have not been incorporated into the design document. Also, there is an apinf-harvester that is supposed to POST harvested apis to the Catalog. Its datamodel should be compared with the Catalog API design.

Goal

• Make changes to the Open API designer file based on the community comments. Comments can be found from apinf.io Feedback tab.
• Check the apinf harvester datamodel. Document suggested changes for harvester.
• Store the document also in APInf docs repository REST API folder
• Replace the current version in apinf.io

Community comments

The following comments are taken directly from the Feedback tab of our APInf Catalog REST API page:

(Rough translations in parentheses)

• Q:Mitä mieltä olette siitä että tarjotaan simppelit esimerkit metodien esittelyssä ennen kuin tulee lista parametreja? Onko niistä apua? (What do you think about offering simple examples in method declarations before presenting a list of parameters? Are examples useful?)
• A: on apua. Vielä jos saa kieliversiot esim. Nodelle ja Pythonille, niin olisi erittäin hyvä lisä. ( Yes, they are helpful. In addition, if there were available versions for e.g. Node and Python, it were good addition)
• Ihan simppeli tilastokin riittää pitkälle, kun sen saa rajapinnan kautta automaagisesti integroitua raportointiin + laskutukseen (Just a simple statistics may be nearly enough, when it is possible to get it via interface automatically integrated into reporting + billing)
• sitten olisi tuohon /apis/ GETiin yksi oleellinen lisäystoive: 1. käyttötilastot valitulta ajanjaksolta 2. autentikaatiovirheet valitulta ajanjaksolta 3. virheet API-kutsuissa valitulta ajanjaksolta. = tilastoja esim. laskutusta varten ja luotettavuuden varmistaminen. (one wish for additional functionality to /apis/GET: 1. use statistitics during a selected period. 2. authentication errors during a selected period. 3. errors in API calls during selected period = statistics for e.g. billing and making sure of trustworthy)
• /apis/updates/ olisi hyödyllistä, jos tätä kautta saisi listattua myös muutetut APIt, esim. schema-muutokset (/apis/updates/ it would be useful, if via it could also be listed modified APIs, e.g. changes in schemas)
• how about authentication? What actions you need to have authentication, which ones can you do anonymously?
• Do we need better instructions for pagination?
• PUT /apis/{id} has a question in the description: Do we need an indication, which field(s) to update? Not sure if this is the best approach in a design-phase API?
• Try out example for /apis/updates/ gives me https://apinf.io:3002/kyyberi/APInf-REST-API/1.0.0/apis/updates/?since=7d&id=undefined&limit=undefined&new_apis_only=false&lifecycle=undefined port 3002? kyyberi?
• It is not clear to me what "API updates" are (/apis/updates/). Is it just a series of possible parameters? Then it should be in just /apis/?
• Testing the feedback tab functionality
• it would be helpful to have a possibility to pass a string (as API NAME) and get in response APIs that closely match provided string. (Just like current APInf search does)

[brylie]

For the record, it was requested that we use the OpenAPI Spec file that was created for the API Catalog to generate a REST scaffold. What would be the goal or outcome of generating the REST scaffold? What would be some possible implications of going 'design first', including code generation, when building the APInf REST API?

cc: @bajiat @kyyberi @marla-singer @matleppa

[kyyberi]

The design has been validated by the potential users aka developers. I suggest strongly that the implementation follows the structure. We preach the practice of automation and avoidance of unnecessary work in development. Using machine readable spec to generate API stub makes sense. Furthermore in my ears implementing API with different structure because selected platform makes it easy is not an acceptable excuse to neglect user defined features. We are building these APIs for developers, not to make life easy for our developers. Find a way to satisfy user needs.

[brylie]

@kyyberi thanks for clarifications.

Furthermore in my ears implementing API with different structure because selected platform makes it easy is not an acceptable excuse to neglect user defined features.

The Architecture Team has made a recommendation that is in alignment with the current proposed structure. We are continuing to discuss the overall strategy for building/maintaining the APInf API, including considerations such as user needs and maintainability, in that thread.

[brylie]

@frenchbread this is our Catalog API design task for the current sprint. Please let us know of anything you might need for your API Bot, or other, tasks.

[frenchbread]

@brylie API Bot is experimental thing, but anyways complete list of APIs available RESTfully would be enough. Additionally, it would be helpful to have a possibility to pass a string (as API NAME) and get in response APIs that closely match provided string. (Just like current APInf search does)

[brylie]

I moved the community comments from the APInf platform to this issue, so we can keep track of them during our re-design.

@bajiat please consider translating the comments from Suomi to English, where applicable, so we can have a shared understanding.

[bajiat]

Assigned to @bajiat for translations. @matleppa Can you look at the comments and changes suggested?

[bajiat]

Let's go through the comments and create new issues on the changes that are required. After this, we should close this issue.