Issue/Help with "Push the candidate configuration"

[cdot65]

Documentation link

https://pan.dev/access/api/prisma-access-config/post-sse-config-v-1-config-versions-candidate-push/

Describe the problem

1. Return status code of 201 is incorrect
2. Example response body is empty
3. Code examples are for GET methods

Suggested fix

1. Update status code to 200
2. include an example response (listed below)
3. Update to showcase a POST method (listed below)

Examples

Example response from the API:

{
    "success": true,
    "job_id": "32",
    "message": "CommitAndPush job enqueued with jobid 32"
}

Example POST method to the API:

curl --location 'https://api.sase.paloaltonetworks.com/sse/config/v1/config-versions/candidate:push' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer mysecrettoken' \
--data '{
  "folders": [
    "Remote Networks"
  ],
  "description": "Postman test"
}'

[welcome-to-palo-alto-networks[bot]]

:tada: Thanks for opening your first issue here! Welcome to the community!

[atav928]

A few comments and some workarounds on your report

200 vs 201

You are correct I didn't even realize it was a 200, but either way the status code should be a 201 not a 200 as 200's are generally with requesting data primarily in a "GET", but this is a "POST", which means you are expecting a change to occur and that would most likely be followed by a a 201 success not a 200.

Defined here:

• 200: “Everything is OK.” This is the code that is delivered when a web page or resource acts exactly the way it’s expected to.
• 201: “Created.” The server has fulfilled the browser’s request, and as a result, has created a new resource.

Code Examples

I don't even look at their examples as they tend to be wrong anyway. So, not sure that's going to change.

Fixes on their Push method

I do not agree with the way Palo handles the push and responses; I believe I have mentioned this a few times to them and reported it. It doesn't provide you with any real data or information on the success of the push as it only provides you the initial push job ID without any children it creates. This can lead to production problems if you use the api just as it is.

I have built code around this to make up for that in my project. The next release will make it easier, but it is a long standing job that you can use a redis server to background the process while it works and responds see my project here that uses Celery, Docker, Redis and my sase api to push the process to the background so when you call back you get a full response that looks like this:

>>> from prismasase.api import API
>>> api = API(folder='Shared')
>>> api.configuration_management.commit(folders=["Remote Networks", "Service Connections"], description="Commit Test")
INFO    : Pushing candiate config for Remote Networks, Service Connections
INFO    : Config Management Push: response={"success":true,"job_id":"598","message":"CommitAndPush job enqueued with jobid 598"}
INFO    : Pushed successfully job_id=598|message=CommitAndPush job enqueued with jobid 598
INFO    : Push returned success
INFO    : Additional job search returned Jobs 600,599
INFO    : Checking on job_id 600
INFO    : Push returned success
INFO    : Checking on job_id 599
INFO    : Push returned success
INFO    : Gathering Current Commit version for tenant 1234567890
INFO    : Current Running configurations are 205
INFO    : Final Response:
{
    "status": "success",
    "message": "CommitAndPush job enqueued with jobid 598",
    "parent_job": "598",
    "version_info": [
        {
            "device": "Remote Networks",
            "version": 205,
            "date": "2023-02-05T17:55:19.000Z"
        },
        {
            "device": "Service Connections",
            "version": 205,
            "date": "2023-02-05T17:55:19.000Z"
        }
    ],
    "job_id": {
        "598": {
            "details": "{\"info\":[\"Configuration committed successfully\"],\"errors\":[],\"warnings\":[],\"description\":\"Commit Test\"}",
            "end_ts": "2023-02-05 17:55:23",
            "id": "598",
            "insert_ts": "2023-02-05 17:54:10",
            "job_result": "2",
            "job_status": "2",
            "job_type": "53",
            "last_update": "2023-02-05 17:55:24",
            "opaque_int": "0",
            "opaque_str": "",
            "owner": "cfgserv",
            "parent_id": "0",
            "percent": "100",
            "result_i": "2",
            "result_str": "OK",
            "session_id": "",
            "start_ts": "2023-02-05 17:54:10",
            "status_i": "2",
            "status_str": "FIN",
            "summary": "",
            "type_i": "53",
            "type_str": "CommitAndPush",
            "uname": "[email protected]",
            "total_time": "90"
        },
        "600": {
            "details": "{\"status\":\"FIN\",\"info\":[\"Go to the Prisma Access Dashboard for real-time status information.\"],\"errors\":[],\"warnings\":[],\"description\":\"Service Connections configuration pushed to cloud\",\"result\":\"OK\"}",
            "end_ts": "2023-02-05 17:56:49",
            "id": "600",
            "insert_ts": "2023-02-05 17:55:26",
            "job_result": "2",
            "job_status": "2",
            "job_type": "22",
            "last_update": "2023-02-05 17:56:49",
            "opaque_int": "",
            "opaque_str": "",
            "owner": "gpcs-ext",
            "parent_id": "598",
            "percent": "100",
            "result_i": "2",
            "result_str": "OK",
            "session_id": "",
            "start_ts": "2023-02-05 17:55:26",
            "status_i": "2",
            "status_str": "FIN",
            "summary": "Configuration push finished",
            "type_i": "22",
            "type_str": "CommitAll",
            "uname": "[email protected]",
            "total_time": "90"
        },
        "599": {
            "details": "{\"status\":\"FIN\",\"info\":[\"Go to the Prisma Access Dashboard for real-time status information.\"],\"errors\":[],\"warnings\":[],\"description\":\"Remote Networks configuration pushed to cloud\",\"result\":\"OK\"}",
            "end_ts": "2023-02-05 17:57:30",
            "id": "599",
            "insert_ts": "2023-02-05 17:55:21",
            "job_result": "2",
            "job_status": "2",
            "job_type": "22",
            "last_update": "2023-02-05 17:57:30",
            "opaque_int": "",
            "opaque_str": "",
            "owner": "gpcs-ext",
            "parent_id": "598",
            "percent": "100",
            "result_i": "2",
            "result_str": "OK",
            "session_id": "",
            "start_ts": "2023-02-05 17:55:21",
            "status_i": "2",
            "status_str": "FIN",
            "summary": "Configuration push finished",
            "type_i": "22",
            "type_str": "CommitAll",
            "uname": "[email protected]",
            "total_time": "30"
        }
    }
}

That returns everything you need to know about a push and actually tells you if it failed or didn't as the jobID that Palo sends in the Push command will always succeed therefore giving you a false positive as it does not tell you about the children that it creates nor does it tell you the version that it comes out as. As you can see from the above my api source code is on github will do that for you.

I just wish I could get a diff on the configuration changes and better response with the rollback which will be another issue I report.

[cdot65]

Would a 202 be more appropriate since the job is still processing in the background?

HTTP Status 202 (Accepted) is a non-committal status code that indicates that the request has been accepted for processing, but the processing has not been completed