1. OMG Mailing List
  2. APIs for Knowledge Platforms 1.1 RTF

Open Issues

  • Issues not resolved
  • Name: api4kp-rtf
  • Issues Count: 5

Issues Descriptions

Modify the interface to make the Swagger 3.0 implementation primary

  • Key: API4KP11-5
  • Status: open  
  • Source: Thematix Partners LLC ( Mrs. Elisa F. Kendall)
  • Summary:

    The initial version of API4KP was based on swagger 2 with the canonical transformation from 2 to 3. A better approach at this point is to start from swagger 3, which has more capabilities and is more modern.

    The resolution impacts the specification as well as several of the machine-readable files.

    The mapping back to swagger 2 may be lossy if we take advantage of new features, so for the RTF we will simply swap the order of operations and defer a more comprehensive approach to a 2.0 update to API4KP.

  • Reported: API4KP 1.0b2 — Fri, 19 Jan 2024 20:23 GMT
  • Updated: Fri, 19 Jan 2024 20:23 GMT

Revise the API4KP ontologies to leverage updates to the Commons Ontology Library v1.1

  • Key: API4KP11-4
  • Status: open  
  • Source: Thematix Partners LLC ( Mrs. Elisa F. Kendall)
  • Summary:

    There are four new ontologies in Commons that contain terms that could be used / reused in the API4KP ontologies. Better alignment would facilitate use of the APIs with knowledge graphs that implement the Commons ontologies. This update would primarily impact the ontologies themselves, although there may be some revision to the specification where the ontologies are documented as well.

  • Reported: API4KP 1.0b2 — Wed, 17 Jan 2024 17:20 GMT
  • Updated: Wed, 17 Jan 2024 17:20 GMT

Revisit Model negotiation : header vs query

  • Key: API4KP11-3
  • Status: open  
  • Source: Mayo Clinic ( Dr. Davide Sottara)
  • Summary:

    API4KP uses a tunneling approach where 'models' of various nature are wrapped in an API4KP "KnowledgeCarrier" object that adds some necessary metadata about the model.

    Implementations that require transport (e.g. based on ReSTful web services) face two problems:

    • the serialization format of the wrapper (JSON, XML or else)
    • the representation and serialization of the model (in various languages, across serializations and formats)

    The former is a classic content negotiation problem, and is expetcted to be handled in the standard way, using Accept-* and Content-* headers

    The latter is a similar but distinct model negotiation problem. The standard mandates not to use the content negotiation headers - so that, for example, a BPMN+XML model can be serialized and embedded in an API4KP+JSON KnowledgeCarrier.
    Insteadd, API4KP model negotiation defines an "X-Accept" header for requests, and uses the KnowledgeCarrier body itself for the analogue of the Content-Type response.

    The use of a header, as opposed to a query parameter, has pros and cons, and should be discussed.
    Ultimately, it comes down to the ability to provide a (persistent) URL to a specific knowledge artifact, using a primary identifier composed by the ID of the carried knowledge Asset, plus a coded identifier of the artifact's form

    (1) keep xAccept as it is
    (2) replace xAccept w/ qAccept
    (3) add qAccept as an optional parameter, together with xAccept

    I am strongly inclined towards (3), for this reason:

    • {assetd}/carrier
      return (any) "canonical" model form

      * {assetd}

      /carrier ? qAccept=formB
      return model form B specifically

    • {assetd}/carrier
      retrieve or generate formB using any form available

      * {assetd}

      /carrier ? qAccept=formA
      retrieve formA, and use it to generate formB if not the same

    Background references:


  • Reported: API4KP 1.0b2 — Thu, 13 Jul 2023 19:01 GMT
  • Updated: Thu, 13 Jul 2023 19:03 GMT

Missing/Default content types may break PSM implementations

  • Key: API4KP11-2
  • Status: open  
  • Source: Mayo Clinic ( Dr. Davide Sottara)
  • Summary:

    Api spec - KnowledgeAssetRepository :: addCanonicalKnowledgeAssetSurrogate

    the body parameter does not specify a content type, which is defaulted to /. Swagger-CodeGenerated clients pass the value to the server, but the server may reject any payload that does not have an explicit content type.
    This behavior has been verified with Spring-Web (2.7), but also (independently) with some enterprise firewall rules.

    Either way, the spec should be explicit, and the use of content types should be reviewed across the 5 OpenApi documents

  • Reported: API4KP 1.0b2 — Wed, 31 May 2023 22:11 GMT
  • Updated: Wed, 31 May 2023 22:50 GMT

ReST specification of some Transrepresentation operations includes two 'body' parameters, which is illegal

  • Key: API4KP11-1
  • Status: open  
  • Source: Mayo Clinic ( Dr. Davide Sottara)
  • Summary:

    The levelTag parameters is incorrectly specified as a body parameter - a role that shuold be reserved to the main operand, the carrier of the artifact to be processed.

    The parameter is a coded string, and does not need to be a body parameter

  • Reported: API4KP 1.0b2 — Sat, 20 May 2023 16:43 GMT
  • Updated: Sat, 20 May 2023 16:43 GMT