Updating API on Apicurio studio by sending a POST with OpenAPI json doc

[killjoy2013]

We have a Nestjs app and creating OpenAPI docs with Swagger. Currently we need to update it on Apicurio manually. We want to automate this update. What would be the best bet? Should we just send a POST request with the updated JSOn docs?
Is there a better flow for this?

[EricWittmann]

What version of Studio are you using?

[killjoy2013]

[EricWittmann]

That's the original (now deprecated) version of Studio. It's fine that you're still using it, just understand that my answer is drawing on my old memories of how that version works... :)

That said, I think you can use this REST API call:

https://github.com/Apicurio/apicurio-studio/blob/0.2.x/back-end/hub-api/src/main/java/io/apicurio/hub/api/rest/IDesignsResource.java#L92-L95

That should update the content of the design. You'll need to have the designId. And you'll need to have an access token from Keycloak to make the call.

[killjoy2013]

@EricWittmann
Is there any documentation to show this flow? 🙏
Where & how to get the access token?
Any API documentation to show some sample requests for this cases? Can you pls direct me to correct resources?

Could not find any API document so far 😢

[EricWittmann]

If you are using Keycloak (I assume you are) then you get the token using OAuth/OIDC, which is pretty standard. A concise explanation for how to do it can be found here:

• http://postan-api-testing.s3-website-us-west-1.amazonaws.com/guides/how-to-get-token-from-keycloak-using-postman/

But it's probably worth reading up on OIDC (OpenID Connect) to understand the auth flows better. Without knowing your specific use-case I cannot guess if there is a more appropriate/secure way to acquire a token than what I linked above.

We do not currently have official API documentation for Studio 0.2 - that version was built using a code-first approach for the API. So the canonical way to learn the API is to look at the JAX-RS code (e.g. IDesignResource.java) that I linked in the answer. You can also use the "Network" tab in your browser while navigating the Studio 0.2 user interface and observe the REST calls it is making to fetch data. The UI exclusively uses the REST API for everything it does, except when editing the content of a Design (where a websocket based approach is used, but that's probably not important to you).

However, I did make an attempt many years ago to document the API in Studio, which you can see here:

• https://studio-ws.apicur.io/sharing/207a9aa9-ee1a-4b25-87bc-9f59dfb5da20

I do not know how accurate that documentation is, so please understand it might not be 100% accurate.

What is accurate would be using the Network tab to sleuth the API. For example, using the Network tab approach I can see that the "View All APIs" UI page makes the following REST call:

Request

GET https://studio-api.apicur.io/designs
Accept: application/json
Authorization: bearer ::REDACTED::

Response

[
    {
        "id": "1186",
        "name": "Template: Beer API",
        "description": "The official Beer API!  Search for both beers and breweries.",
        "createdBy": "eric.wittmann@gmail.com",
        "createdOn": "2018-04-20T15:31:08.115+00:00",
        "tags": [
            "brewery",
            "beer"
        ],
        "type": "OpenAPI30"
    },
    {
        "id": "4025",
        "name": "Apicurio Studio API",
        "description": "The back-end REST API for Apicurio!",
        "createdBy": "eric.wittmann@gmail.com",
        "createdOn": "2018-10-15T15:58:48.196+00:00",
        "tags": [],
        "type": "OpenAPI30"
    }
]

That said, the primary REST API call you are interested in is never made by the User Interface (because it does editing using a websocket as mentioned). But pretty much all other REST API calls are made at some point by the UI.

[EricWittmann]

Note: after looking more closely at the API documentation I linked, it was never completed and is missing a LOT of operations. So it might not be all that useful.