Forum Discussion

HenrikHL's avatar
HenrikHL
Frequent Contributor
4 years ago

Pitfalls when publishing an API referencing Domains that are unpublished

Hi, I have stumbled onto a problem when publishing APIs. I have started using the Domains to store common types and components shared among APIs. The Domains are not yet published. When I publish my...
  • mhiggins's avatar
    mhiggins
    4 years ago

    the webhook listener should not be deployed on the SwaggerHub VM. I would suggest a small Linux instance on the same sub-net. 

    there I would run a small node.js listener that accepts the POST from SwaggerHub and parses the json copy of the spec that is included in the POST payload. 

    the parsing would look for $refs that contain the “…/domain/…” url inductive of a domain reference. Parse out the domain location (organization), name and version contained the the url, then use either the swaggerhub cli or the SwaggerHub Registry Api to publish that domain/version. Repeat until the spec is completely parsed. 

    the node.js code to do this should be fairly simple, you’ll just need to be able to find the $refs that are remote anchors, then pick out the 3 sub-strings that describe the domain. 

joejoyce's avatar
joejoyce
Staff

Hey HenrikHL, thanks for getting in touch. This sounds like it could be a good use case to bring to the SwaggerHub product team. I'm interested to hear more about the scenario. Have you been finding that publishing an API that references unpublished domains is causing issues for your users or workflows?

HenrikHL's avatar
HenrikHL
Frequent Contributor
4 years ago

Hi joejoyce - thanks for reaching out.

I have previously released APIs (by not using Domains) - this works fine as once the API is published - it cannot be modified.

After talking with some of your colleagues I was introduced to Domains - which sounds like a great idea (we reuse a lot of definitions between different APIs). We are about to release the next big API (actually we are going to release 4 new APIs based on Domains). There are a lot of worries that when publishing the API domains can still change - as in types, names, everything referenced from an API to a Domain can change!

I would suspect this is an error as the hole point of publishing an API is to make it readOnly.

 

If you want a concrete example I can give one here:

CustomerAPI v1.0.0 containing a GET /customers

in the CustomerAPI definition of the above response a reference to the Customer-component defined in GlobalDomain v1.0.0 is inserted:

 

/customers:
  get:
    responses:
      '200':
        description: Request successful
        content:
          application/json:
            schema:
              $ref: 'https://api.swaggerhub.com/domains/XXXorg/GlobalDomain/1.0.0#/components/schemas/customer'

 

Now in GlobalDomain v1.0.0 i start by defining Customer like this:

 

components:
  schemas:
    customer:
      type: string
      ...

 

(To make it simple - customer is a type: string)

I then publish CustomerAPI v1.0.0 with the endpoint GET /customers the response here is a string (for now)

 

Someone then opens GlobalDomain v1.0.0 (since it is not published and therefore NOT readOnly) and changes customer to:

 

components:
  schemas:
    customer:
      type: integer
      ...

 

(Changes type:string -> type:integer)

Now the published GET /customers endPoint of CustomerAPI returns an integer instead of a string!

 

I would be glad to take this up with the SwaggerHub product team - let me know how to contact them and I will do so 🙂

  • mhiggins's avatar
    mhiggins
    Staff
    4 years ago

    I would suggest using a workbook integration here. Set up an “on-publish” integration for the API and then post-process the json on the webhook listener and force publish each of the domain/version references. 

    • HenrikHL's avatar
      HenrikHL
      Frequent Contributor
      4 years ago

      Thanks for the solution - I have not tried this.

      I can see it is possible to create an "On publish" integration when an API is published and then send to a WebHook.

      From here it is a little vague for me what to do? Is it possible to setup a webhook listener on SwaggerHub which then can trigger a force publish on the Domain. If so - how do I know which Domain the API references - is this something that can be automatically set up - or do you see that as "manual" setup when creating the "On publish" integration (maybe as a header(s)?!?)

      • mhiggins's avatar
        mhiggins
        Staff
        4 years ago

        the webhook listener should not be deployed on the SwaggerHub VM. I would suggest a small Linux instance on the same sub-net. 

        there I would run a small node.js listener that accepts the POST from SwaggerHub and parses the json copy of the spec that is included in the POST payload. 

        the parsing would look for $refs that contain the “…/domain/…” url inductive of a domain reference. Parse out the domain location (organization), name and version contained the the url, then use either the swaggerhub cli or the SwaggerHub Registry Api to publish that domain/version. Repeat until the spec is completely parsed. 

        the node.js code to do this should be fairly simple, you’ll just need to be able to find the $refs that are remote anchors, then pick out the 3 sub-strings that describe the domain.