Improve get jobs and get job logic with new search parameters #1695

paaragon · 2025-08-01T08:55:30Z

Summary

This PR adds the new jobs and provider_jobs parameters in the client:

status
created_after
function_name (only for jobs)

And in the backend the changes applied are:

Migrated /jobs and /jobs/provider endpoints to new architecture
Added new filters: status, function and created_after date
Added tests to cover new filters
Added a new ProgramSummarySerializer so we return less info about the program in the job lists

Details and comments

After trying multiple solutions, I think the best pattern is to return a QuerySet in the repository but not propagate it to the endpoint. The use-case should return a business object, not the QuerySet.

I created the create_paginated_response utility method that should be used in future endpoints to maintain consistency between responses.

Also, the previous response was returning different response types. I removed the non-paginated response because it wasn't being used in the client.

:

korgan00

Good job! this is nice.
Since I was working in the files migration in parallel, naturally we didn't developed same solution. I have some lines to discuss.

If you have some time, take a look to the PR and review it because you probably have some comments for me :)

korgan00 · 2025-08-01T17:09:13Z

gateway/api/repositories/jobs.py

clean and neat

korgan00 · 2025-08-01T17:18:10Z

gateway/api/use_cases/get_jobs.py

+    def __init__(  # pylint:  disable=too-many-positional-arguments
+        self,
+        user,
+        limit: Optional[int],
+        offset: int = 0,
+        type_filter: Optional[TypeFilter] = None,
+        status: Optional[str] = None,
+        created_after: Optional[datetime] = None,
+        function_name: Optional[str] = None,
+    ):
+        self.user = user
+        self.limit = limit
+        self.offset = offset
+        self.type_filter = type_filter
+        self.status = status
+        self.created_after = created_after
+        self.function_name = function_name


I have two comments here:

To remove the "too many positional arguments" maybe you can use the JobRepository >JobFilter dataclass. I think it will also be more readable.

I was migrating the files endpoint and I put the args in the execute instead of the init. I think it is good to have consensus on this. In my opinion, most of this parameters are not a "permanent" state, are more related with the action. Also it simplifies the code, we don't have to set object variables, just use them.

What do you think?

you are right, I though about passing JobFilters to the use case and discard it but it will be a better solution than passing all the individual filters.

I also like the idea of moving the arguments to the execute method.

korgan00 · 2025-08-01T17:24:05Z

gateway/api/use_cases/get_provider_jobs.py

+class ProviderNotFoundException(Exception):
+    """Provider not found or access denied."""
+
+
+class FunctionNotFoundException(Exception):
+    """Function not found or access denied."""
+


In the files migration i created a generic NotFoundException in the domain folder: https://github.com/Qiskit/qiskit-serverless/pull/1696/files#diff-e6da6866795b4c157d9b9e887eb27622f036a9dc512d30e5097a301df1d5001c

Also I created an additional decorator to quickly manage the possible NotFoundExceptions (and other that can be created later) and create the corresponding Response. The only cons is that you have to set the message when you create the exception to inform about the issue.

korgan00 · 2025-08-01T17:25:17Z

gateway/api/v1/views/get_provider_jobs.py

+    try:
+        jobs, total = GetProviderJobsUseCase(**input_data).execute()
+    except ProviderNotFoundException:
+        return Response(
+            {"message": f"Provider {input_data['provider']} doesn't exist."},
+            status=status.HTTP_404_NOT_FOUND,
+        )
+    except FunctionNotFoundException:
+        return Response(
+            {
+                "message": f"Qiskit Function {input_data['provider']}/{input_data['function_name']} doesn't exist."  # pylint: disable=line-too-long
+            },
+            status=status.HTTP_404_NOT_FOUND,
+        )


In the files migration i created a generic NotFoundException in the domain folder: https://github.com/Qiskit/qiskit-serverless/pull/1696/files#diff-e6da6866795b4c157d9b9e887eb27622f036a9dc512d30e5097a301df1d5001c

Also I created an additional decorator to quickly manage the possible NotFoundExceptions (and other that can be created later) and create the corresponding Response. The only cons is that you have to set the message when you create the exception to inform about the issue.

korgan00 · 2025-08-01T17:27:33Z

gateway/api/v1/views/get_jobs.py

+def serialize_input(request):
+    """Parse and validate query parameters from the request."""
+    user = request.user
+
+    limit = parse_positive_int(
+        request.query_params.get("limit"), settings.REST_FRAMEWORK["PAGE_SIZE"]
+    )
+    offset = parse_positive_int(request.query_params.get("offset"), 0)
+
+    type_filter = None
+    type_param = request.query_params.get("filter")
+    if type_param:
+        try:
+            type_filter = TypeFilter(type_param)
+        except ValueError as exc:
+            raise ValueError(
+                f"Invalid type filter. Must be one of: {', '.join([e.value for e in TypeFilter])}"
+            ) from exc
+
+    status_filter = request.query_params.get("status")
+
+    created_after = None
+    created_after_param = request.query_params.get("created_after")
+    if created_after_param:
+        created_after = parse_datetime(created_after_param)
+        if created_after is None:
+            raise ValueError(
+                "Invalid created_after format. Use ISO 8601 format (e.g., '2024-01-01T00:00:00Z')"
+            )
+
+    function_name = request.query_params.get("function")
+
+    return {
+        "user": user,
+        "limit": limit,
+        "offset": offset,
+        "type_filter": type_filter,
+        "status": status_filter,
+        "created_after": created_after,
+        "function_name": function_name,
+    }


I think this is a bit complex to read. Maybe a Serializer class fits better in here.

korgan00 · 2025-08-01T17:28:25Z

gateway/api/v1/views/get_provider_jobs.py

+def serialize_input(request):
+    """
+    Prepare the input for the end-point with validation
+    """
+    user = request.user
+
+    limit = parse_positive_int(
+        request.query_params.get("limit"), settings.REST_FRAMEWORK["PAGE_SIZE"]
+    )
+    offset = parse_positive_int(request.query_params.get("offset"), 0)
+
+    status_filter = request.query_params.get("status")
+
+    created_after = None
+    created_after_param = request.query_params.get("created_after")
+    if created_after_param:
+        created_after = parse_datetime(created_after_param)
+        if created_after is None:
+            raise ValueError(
+                "Invalid created_after format. Use ISO 8601 format (e.g., '2024-01-01T00:00:00Z')"
+            )
+
+    provider = request.query_params.get("provider")
+    function_name = request.query_params.get("function")
+    if not provider or not function_name:
+        raise ValueError("Qiskit Function title and Provider name are mandatory")
+
+    return {
+        "user": user,
+        "limit": limit,
+        "offset": offset,
+        "status": status_filter,
+        "created_after": created_after,
+        "provider": provider,
+        "function_name": function_name,
+    }


Same here, maybe we can try with a Serlializer class

korgan00 · 2025-08-01T17:32:31Z

gateway/api/v1/views/utils.py

korgan00 · 2025-08-01T17:32:57Z

gateway/api/v1/urls.py

@@ -46,4 +46,4 @@
    basename=v1_views.CatalogViewSet.BASE_NAME,
 )

-urlpatterns = router.urls + RouteRegistry.get()
+urlpatterns = RouteRegistry.get() + router.urls


# Conflicts: # gateway/api/v1/views/files.py

korgan00 · 2025-08-22T16:46:50Z

the jobs_new folder should be renamed to jobs when we delete the jobs.py file. Then we should be able to delete also all the endpoints name properties because it will be auto-calculated

Tansito

I just left a couple of comments plus we need to add also in the client the same filters as we added for the jobs method.

Tansito · 2025-08-22T18:14:44Z

gateway/api/repositories/functions.py

+    ) -> Optional[Function]:
+        """
+        This method returns the specified function if the user is
+        the author of the function or it has a permission.


I think we need to update the description as this method doesn't check the permission.

Also the arguments need to be updated.

Tansito · 2025-08-22T18:24:14Z

gateway/tests/api/test_job.py

+        self.client.force_authenticate(user=user)
+        provider = "default"
+        function = "Docker-Image-Program"
+        created_after = "2023-02-02T00:00:00.000000Z"


If I can be honest I don't think the user will introduce us this format in the date. Can we change the tests with created_after with a more realistic date? Like: 2023-02-02, for example.

Tansito · 2025-08-22T18:29:58Z

client/qiskit_serverless/core/clients/serverless_client.py

        limit = kwargs.get("limit", 10)
        kwargs["limit"] = limit
        offset = kwargs.get("offset", 0)
        kwargs["offset"] = offset
+        status = kwargs.get("status", None)
+        kwargs["status"] = status
+        created_after = kwargs.get("created_after", None)


I would probably validate here also that the created_after is a valid date with fromisoformat.

paaragon added 16 commits July 21, 2025 10:56

[wip] feat: migrate get jobs endpoint

2b60d77

[wip] feat: migrate get jobs endpoint

23eeec4

[wip] first version of migrate-get_jobs-endpoint

f952fbc

[wip] first version of migrate-get_jobs-endpoint

4f58099

first version of get-jobs endpoint

cc04af8

add new filters (status, created_after) for get_jobs

820a0a2

add get_provider_jobs endpoint

7b2e0a8

add filters in jobs endpoints:

550b19b

:

Merge branch 'main' into feat/migrate-get-jobs-endpoint

49e9733

add test to cover get_jobs and get_provider_jobs

9f2ea0c

fix jobs repository style

86027d2

fix lint

6aaca26

refactor

af5fe91

add programsummaryserializer

71fd9e6

Merge branch 'main' into feat/migrate-get-jobs-endpoint

287d54e

update jobs and provider_jobs client methods

8a909c2

paaragon requested a review from a team as a code owner August 1, 2025 08:55

korgan00 approved these changes Aug 1, 2025

View reviewed changes

Tansito changed the base branch from main to feat/migrate-get-jobs-endpoint August 7, 2025 17:34

Tansito changed the base branch from feat/migrate-get-jobs-endpoint to main August 7, 2025 17:35

Tansito mentioned this pull request Aug 12, 2025

Feat/migrate get jobs endpoint #1685

Closed

3 tasks

Tansito changed the title ~~Feat/migrate get jobs client methods~~ Improve get jobs and get job logic with new search parameters Aug 12, 2025

Tansito self-requested a review August 12, 2025 15:00

korgan00 and others added 7 commits August 20, 2025 18:51

Merge branch 'main' into feat/migrate-get-jobs-client-methods

5a5e336

# Conflicts: # gateway/api/v1/views/files.py

rework input serializer

bdfa3eb

fix imports

6c35752

unroll output serializer

583fe48

rename use case to be consistent

2aeeee9

change doc comment

64a15df

Merge branch 'main' into feat/migrate-get-jobs-client-methods

2197dbd

Tansito requested changes Aug 22, 2025

View reviewed changes

Improve get jobs and get job logic with new search parameters #1695

Are you sure you want to change the base?

Improve get jobs and get job logic with new search parameters #1695

Conversation

paaragon commented Aug 1, 2025 • edited by Tansito Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Details and comments

Uh oh!

korgan00 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

korgan00 commented Aug 22, 2025

Uh oh!

Tansito left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

paaragon commented Aug 1, 2025 •

edited by Tansito

Loading

Tansito left a comment •

edited

Loading