response for "Try it out" in docs

[valpesendorfer]

Description
Hi,

I'm creating an API where authenticated users can trigger a processing chain. The chain requires an input which is provided by the user in the request body.

I'm wondering if there's a way to check if a request has been made through the doc interface via the "Try it out" feature. This way I could return a pre-defined response instead of triggering the chain (which will most likely end in an exception).

I could check the body for the default arguments I've defined and detect it this way. However, that seems a bit hacky, so I hope there's some functionality within FastAPI I could use for that purpose.

[tiangolo]

That would require some kind of central storage for the status of that call, like a database, a file, etc. So, it's not something provided by FastAPI.

But you can easily implement it yourself. I imagine once you start a processing chain you would get an ID for the process, or some way to determine if that has already been triggered.

Then save that (let's say it's an ID) in some storage (database, Redis, JSON file), and then, in your path operation, check if that already exists and return that value if it exists, otherwise start the chain, save the ID to the store and return that.

[valpesendorfer]

Thanks for your answer @tiangolo.

That's currently what I've already implemented:

If a registered user calls the specified endpoint with a defined request body, a processing job is created that is identified by a UUID and registered in a database.

My issue is, that a registered user can log into the docs panel and could trigger the processing with the example request body that is provided for the documentation, which is not desirable.
So Ideally, creating a request through the doc interface also supplies a "fake" documentation response without actually creating a job.

An easy way would be to just check if the request body is identical to the one used in the docs ... but this isn't very robust.

[tiangolo]

If what you want to do is document the response, you can add response examples.

from fastapi import FastAPI

app = FastAPI()


@app.get(
    "/",
    responses={
        "200": {
            "content": {
                "application/json": {
                    "examples": {
                        "response 1": {
                            "summary": "Some description",
                            "value": {"some key": "some value"},
                        }
                    }
                }
            }
        }
    },
)
def read():
    return {"some key": "a different value"}

Otherwise, I'm not sure how would you want to handle it. Why wouldn't it be desirable for the user to trigger the processing with the example request in the docs? What's wrong with that?

[valpesendorfer]

The response documentation is just for display in the documentation, right? It's not going to be actually returned when the user triggers the button.

Maybe bit more context helps:

The endpoint is a POST route, which allows designated users (external data providers) to trigger a processing chain. This however, requires one or more valid metadata documents on the user's side. These are supposed to be supplied by specifying a list of URLs, which are read by the processing chain.

To document how the POST call needs to look like, I've created documentation with some "fake" URLs ... so if an authorized user triggers the processing chain with the example in the doc panel, the chain will fail.

Now writing these lines I'm thinking of some alternative ways to re-design this workflow, that might circumvent this "issue". But would be still interesting, to have the option to e.g. return a fake response for these fake requests.

[tiangolo]

I'm not sure I'm understanding your use case correctly...

These are supposed to be supplied by specifying a list of URLs, which are read by the processing chain.

So, the user sends a POST with a JSON body containing URLs?

Are those URLs part of the same FastAPI app?

The idea of the docs UI is that it allows interacting with the actual API, so that the users can use the real thing through it, the same way they would do it via a frontend, mobile app, etc. So returning mocked responses in the docs would defeat that purpose.

Maybe a simple workaround for your use case could be to have a query parameter production that is by default False, and only when set to True the API would actually perform the costly action.

But that would also mean that your actual client code would have to set that query parameter to True everywhere...

But that might work for your use case.

[github-actions]

Assuming the original issue was solved, it will be automatically closed now. But feel free to add more comments or create new issues.