topic Re: Machine readable HTTP API (Mgmt) specifications ? in API / CLI Discussion

Machine readable HTTP API (Mgmt) specifications ?

Gerard_Fowley — Wed, 17 Nov 2021 22:06:09 GMT

Hi,

Ruby developer here. I had a look at the GitHub repos andI do not see a API SDK for Ruby.

It is extremely tedious work extracting information from the (very comprehensive and nice) human readable docs to manually type the specification for an API client.

Is there a machine readable API specification I can use to create my own HTTP API client library ?

I am thinking about something like the OpenAPI standard format that I can use tools like Swagger to generate client code.

Or does the web API support HyperMedia for API discovery ?

In a pinch, any machine readable file format would beat trying to scrape the APIs documentation pages.

Thanks

-gf-

Re: Machine readable HTTP API (Mgmt) specifications ?

PhoneBoy — Sat, 20 Nov 2021 00:26:17 GMT

@Omer_Kleinstern any comment here?

Re: Machine readable HTTP API (Mgmt) specifications ?

Omer_Kleinstern — Tue, 23 Nov 2021 15:24:30 GMT

Hi,

We don't have an SDK for Ruby.

The API documentation is generated from a JSON file but it is not in any standard format and can't be used in any of the mentioned tools.

Thanks,

Omer

Re: Machine readable HTTP API (Mgmt) specifications ?

Gerard_Fowley — Tue, 23 Nov 2021 16:03:27 GMT

Hi Omer,

Thanks for replying.

I see that the API documentation web page is dynamically created from JSON files. They are broken into diffs between versions (probably to reduce bandwidth) leaving much re-assembly to be done to extract an API spec for the latest version.

Having an original version-specific file(s) to parse would greatly reduce the quantity of work required to create our own client.

Can the API spec JSON file be made available (with no expectations of support) for those of us who need to create their own client ?

Thanks

-gf-

Re: Machine readable HTTP API (Mgmt) specifications ?

Vivek_Ravi — Tue, 19 Mar 2024 12:51:29 GMT

I am looking for a Swagger 2.0 or OPEN API3.0 specification file for an Integration Model. Do let me know if anyone has it in Json format or direct me where to get one for GAIA.

Re: Machine readable HTTP API (Mgmt) specifications ?

Gerard_Fowley — Tue, 19 Mar 2024 17:44:35 GMT

Hey, your comment prompted me to look into this again...

Since last time I checked, there are now links to Postman collection specs for some APIs on the Checkpoint API page:

https://sc1.checkpoint.com/documents/latest/api_reference/index.html

Look for links titled "Copy URL with API spec", they point to Postman Collection JSON files. There is one for the Management API I was looking for, did not see one for the GAIA API. Maybe there will be in future.

That started me down the rabbit hole of Postman conversion to OpenAPI format with open source tools:

https://github.com/kevinswiber/postman2openapi

https://github.com/joolfe/postman-to-openapi

However, both formats can be quite complex and there is no simple one-to-one mapping. Both tools made an incomplete conversion to OpenAPI for the management API, but postman-to-openapi came closest. It's output may be useful as the basis of a manual conversion.

I also found the Postman code generators project:

https://github.com/postmanlabs/postman-code-generators

It seems to generate code snippets for individual API requests. That may be useful if your use case only needs a few different requests, but it may not scale to a complete client.

I'll look into this some more as time allows. Let me know if you discover anything interesting.

Thanks

-gf-

Re: Machine readable HTTP API (Mgmt) specifications ?

Vivek_Ravi — Wed, 20 Mar 2024 04:37:40 GMT

Thanks for the recommendations Gerard_Fowley, yeah the link converts the JSON/postman files to Open API specification, but the integration model rejects it saying non-compliance with Open API specifications. Will explore more into this.

Re: Machine readable HTTP API (Mgmt) specifications ?

Vivek_Ravi — Fri, 29 Mar 2024 04:22:01 GMT

After researching a bit more on this one, I finally created Swagger JSON for GAIA. Attached is the file. Unlike other adapters, the GAIA's Authentication is empty. Can someone guide me what type of authentication does this uses. The tool I am using provides three type of Authentications

API Key

"authentication": {
  "API-Token": {
    "value": "<INSERT API-Token HERE>"
  }
},

HTTP (Basic & Bearer)

Basic

"authentication": {
          "httpBasic": {
            "username": "<INSERT username HERE>",
            "password": "<INSERT password HERE>"
          }
      },

JSON

Bearer

"authentication": {
          "bearerAuth": "<INSERT bearerAuth HERE>"
      },

JSON

Oauth2

"authentication": {
  "oauth2": {
    "token": {
      "access_token": "<INSERT access_token HERE>",
      "token_type": "Bearer"
    }
  }
},

Re: Machine readable HTTP API (Mgmt) specifications ?

Bob_Zimmerman — Fri, 29 Mar 2024 17:18:31 GMT

OAuth is closest, but Check Point's management API authentication isn't actually OAuth.

You must call /login with the credentials in the body of the request. It responds with a JSON object. The key 'sid' contains a value which you must add to the 'X-chkp-sid' header in all subsequent requests. The token is invalidated after calling /logout or after 10 minutes with no API calls by default. You can request a different validity period in the call to /login, but the actual timeout will be in the key 'session-timeout' in the /login response. If building something user-interactive, you can call /keepalive to reset the timeout without actually changing anything on the management.

Check Point management servers do not perform 401 authentication challenges, and do not accept session tokens in cookies.

Re: Machine readable HTTP API (Mgmt) specifications ?

Vivek_Ravi — Mon, 01 Apr 2024 11:34:45 GMT

Thanks @Bob_Zimmerman for your answer. Yeah indeed we use the above said method in the Postman. But I am using a automation tool called Itential. It has Integration Model based on OpenAPI 3.0 or Swagger 2.0. I imported the GAIA's OpenAPI file to Itential and it converted all the HTTP requests as tasks.

Here is how the Itential imported the Integration file as, the integration isn't working as expected. I believe there is something weird with "authentication":"" part

{
"name": "Dallab Gaia",
"model": "@itential/adapter_GAIA API-1.6:1.0.0",
"type": "Adapter",
"properties": {
"id": "Dallab Gaia",
"type": "GAIA API-1.6:1.0.0",
"brokers": [],
"groups": [],
"properties": {
"server": {
"protocol": "https",
"host": "192.168.1.1",
"base_path": "/gaia_api",
"port": 443
},
"version": "1.0.0",
"authentication": {},
"tls": {
"enabled": false,
"rejectUnauthorized": true
}
}
},
"isEncrypted": true,
"loggerProps": {
"log_max_files": 5,
"log_max_file_size": 1048576,
"log_level": "error",
"log_directory": "/opt/itential/logs",
"log_filename": "pronghorn.log",
"console_level": "info",
"description": "Logging"
},
"virtual": true
}

Here is the link to Itential's Token management https://docs.itential.com/docs/integration-token-management