how to use openapi and shuffle?

[falcorocks]

Hi @frikky , I'm pretty new to openapi development workflow, so bear with me. I'm pretty confused. I understand what openapi does, but I just don't understand what is the suggested workflow with using it within shuffle. I more or less understood how to use openapi normally and how to use it to make custom shuffle apps. What I don't understand is how (if possible at all) to use openapi specifications on their own. Maybe this issue could come up useful for other superbeginners like myself 😅

Normal openapi workflow:

• the user develops and deploys the api server by himself
  1. an api can be described with openapi specification, which is awesome
  2. server code and docs can be generated automatically, which is awesome
  3. user still needs to implement the functionality of the endpoints
  4. user still needs to package the project in a deployable format (for example with a docker flask image)

Normal shuffle app workflow:

• the user develops the api server but deployment is taken care by shuffle (?)
  1. write openapi specification
  2. (?) generate an app.py from it. How? is there a specific generator to use? I'm using

     docker run --rm 
     -v $PWD:/local openapitools/openapi-generator-cli generate \
     -i /local/openapi/api.yml \
     -g python-flask -o /local/codegen

  3. (?) alter the app.py to use from walkoff_app_sdk.app_base import AppBase and to look like your example
  4. package the app.py in a Dockerfile based on frikky/shuffle docker image as by example

Openapi shuffle app workflow

• the user writes openapi specification (like those in this github repository) and then automagically everything works (???)
  1. write openapi specification
  2. (?) put it where?
  3. (?) shuffle loads it and deploys an app somehow?

---

As I wrote this, I started to think that:

• Openapi shuffle app workflow does not exist
• the openapi declarations of this repository simply describe api running on a remotely and independently deployed server (for example by following the first workflow)

My questions, if the above is correct, is then:

• how should I build my app? why should I deploy it as a shuffle app when I can just build it as a regular flask app? what is the advantage? ease of deployment I suppose? Will a regular flask app work with shuffle?
• If I don't develop a shuffle app and go with regular Flask app, where should I place the openapi declaration in my shuffle deployment?

[frikky]

Hey and thanks for telling us here! This is a concept we've been working on for a long time, but we don't know whether it's understandable yet. This may have to do with me being lazy and not writing documentation for it yet :fire_extinguisher:

Before getting into specifics, I'd like to say that we WANT to focus on OpenAPI. This is because I have had too many problems with product lock-in in the past, and that OpenAPI specifications makes it possible to use what you make outside Shuffle as well.

Anyway, you're on point with there being three areas:

1. App creation with Manual Python code
   • These are apps specified in the Shuffle-apps folder. These are manually created, and can be quickly developed for custom actions that are not just REST API's.
   • These require two things: api.yaml file (defines actions) & src/app.py file (actual python code). This is the part we haven't documented well yet, but I'd suggest you have a look at the python playground app.
   • If you want to edit/create an app, I'd suggest copying the folder (e.g. python-playground) to the shuffle-apps folder in your Shuffle directory (shuffle/shuffle-apps). This button in the GUI will hotload these apps, then you can instantly test it in a workflow.

Here's an image of an app made manually (Shuffle Tools). Take note it does NOT have the "download" button. This is because the download button is for OpenAPI only.

2. App creation from scratch (Generates OpenAPI for you!)
   • Try to not think about it as OpenAPI, but just as a way to interact with REST API's. If it sucks, please tell us, and we'll keep updating it until it's good. I personally ALWAYS start by trying to make new apps in the creator and move to python if I can't do it there.
   • This can be exported as OpenAPI. This means you can easily share it with other companies etc.
   • By clicking this button, you get access to an empty app creator view. "Actions" in this case, are the API-calls to be made. In this specific case, I added an action that does "GET" to the path /. This can be

If you are looking at an API, they may have examples. Try pasting them in here, and it will build out the action based on the curl statement!

When done, you click "Save", and you'll get access to the app in any workflow! This can be hotloaded as well, meaning if you update the app, you can still use the old one, but if you drag in the app again, it will have the new actions you may have added. You can also export them, as seen above.

3. App creation FROM OpenAPI (gives you access to further edit it)
   • There's no real difference between this and the previous step, except when you import a specification, it will fully build for you. Here's an example tweet about how it works
   • This can also be exported / imported from Shuffle. The whole point is you CAN use Shuffle as an OpenAPI editor if you want, but the priority is to create apps fast, that are universally usable.

Hope this helps :D

[falcorocks]

Thank you very much for the quick and super exhaustive reply! For my use case, I will probably go with the first option you listed, manually creating the python code.

The thirds workflow is still intriguing to me though, because I may want to deploy my app in other projects as a standard Flask app. Correct me if I'm wrong:

1. write openapi declaration
2. generate backend with some tool in whatever language
3. deploy (for example as docker container based on flask+connexion)
4. add the openapi declaration to shuffle by drag and drop in the UI: is this the only way to do this?
   • shuffle will automagically generate the client side code to perform the requests towards the server url specified in the openapi

If I understand it correctly and it works like this then:

• this is really awesome
• I may consider doing this like this instead!

---

I will just try by myself what I wrote above, but I will report back as I believe it could help others ;)

---

BTW what you are doing here is really great. My team is using your tool for a project. I hope we can contribute back soon!

[frikky]

Extended docs have been added for both creation and management:

https://shuffler.io/docs/app_creation https://shuffler.io/docs/apps

Closing this, as it would be ideal if everything goes through there.