2.1.10 API Specification - Axway-API-Management-Plus/apim-cli GitHub Wiki

Of course the API-Specification as OpenAPI/WADL and WSDL is key for the state of the API and changes to it must be handled like any other API-Property defined "manually" in the API-Configuration.

That means, when the desired API-Definition is changed, it must be recognized as a change and replicated into the API-Manager. The program is doing exactly this for you.

How API-Specification changes are detected?

The OpenAPI-, WADL- or WSDL-File itself isn't parsed field by field to identify changes, instead the program is using internally a Byte-Comparison. In other words: Even a small change, like a an additional whitespace, or the line-ending-format (DOS vs. UNIX) is recognized as a change between the actual and the desired state and will lead to the needed actions to get the new specification into API-Manager.

However, as the program is designed to be part of a CI/CD-Pipeline working based on a Version-Control-System it's unlikely that unwanted changes are made to the API-Specification.

Options to provide the API-Specification

You have three options to provide the API-Specification to the tool:

1. Local filesystem

Provide a relative or absolute path to the API-Specification file. This path must be relative to the API-Configuration file.
Examples:
-a sample/petstore.json
-a /home/git/any/path/myswagger.json

⚠️ Local files are not supported for WSDLs as the API-Manager doesn’t support import a WSDL from a local file!

2. Remote URL reference by file

In cases you want reference a Remote API-Reference file, but still requiring to version-control this information, create a file such as:
any-name-of-my-swagger.url
In the first line of the file provide the URL to the JSON-Based Swagger- or WSDL-File. This may optionally include username/password for a HTTP-Basic authentication. Format:
[myuser/mypasswd@]https://any.host.com/path/to/swagger.json
Example including username and password:
chris/myverysecurepassword@https://any.host.com/path/to/swagger.json

⚠️ Make sure to quote the URL properly when calling on command-line/script!

It is important to know, that the tool running on a CI/CD-Slave must have access to that endpoint in order to download the API-Specification. It is NOT the API-Manager downloading the file.

3. Remote URL interactively provided

In cases where you want to execute the tool interactively and just simply using a URL, you can provide it in the same format to the -a parameter.
Format:
-a [myuser/mypasswd@]https://any.host.com/path/to/swagger.json
Example with the optionally provided username & password:
-a chris/abc123@https://any.host.com/path/to/swagger.json

⚠️ Make sure to quote the URL properly when calling on command-line/script!

The API-Specification can be either provided as parameter -a or directly in the API-Configuration file as shown in this example:

{
    "name": "Minimal API",
    "path": "/minimal/api/v1",
    "state": "unpublished",
    "version": "1.0.0",
    "apiSpecification": {
        "resource": "samples/petstore.json"
    },
    "organization": "API Development"
}

apiDefinition is deprecated.

Filter API-Specifications

From version 1.8.0 you have the possibility to filter the API specification to import only selected operations into the API Manager.
This is useful if you reference an external API specification you have no control over or want to import an API into the API Manager multiple times with a different set of methods to assign visibility and permissions on each.
You can include or exclude operations based on the path plus HTTP-Method, and/or tag. For HTTP-Method you can use a "*" for all HTTP-Methods.

To filter the API specification you have to configure it as an apiSpecification object in the API config file. You cannot filter the API specification if you use the -a parameter. The field apiDefinition is still supported, but it is deprecated and does not provide filtering capabilities either.

Some rules:

if no include rule is specified, then by default operations and models are all included
- so if either an include tag or path filter is present, then all paths/operations will be filtered accordingly
- if an include filter for a model is given, then all models will be filtered accordingly
Path and tag filter in a Filter object are interpreted as AND
- in the example below, the paths settings are only applied to operations with tag user
exclude overwrites the include
- specific path filters overwrite wildcard path filters
- in other words, you can use for instance a tag as an include and then take out (exclude) individual methods of the tag
- but you can't, for example, exclude a complete tag and include individual operations again via path

{
  "name": "Filtered API",
  "path": "/filtered/api",
  "state": "published",
  "version": "1.0.0",
  "organization": "API Development",
  "apiSpecification": {
    "resource": "../petstore.json",
    "filter": {
      "include": [
        {
          "tags": [ "pet", "store" ]
        },
        {
          "tags": [ "user" ],
          "paths": [ "/user/{username}:*", "/user/login:GET", "/user/logout:GET" ]
        }
      ],
      "exclude": [
        {
          "paths": [ "*:DELETE" ]
        },
        {
          "models": [ "ApiResponse" ]
        }
      ]
    }
  },
}

In the example above the Petstore API is imported, but only operations tagged with "pet" or "store". Additionally, some individual paths for users are also included. But, all DELETE operations and for some reason the operation the POST /pet/{petId} should be removed.

Please note that if you export such a filtered API, you will of course get the filtered API specification, since the API manager only got this filtered version.

Supported API-Specifications

The following definitions/specifications are supported:

Specification	Format	Filter	Supported	Comment
OpenAPI 3.0	JSON/YAML	Yes	Yes	Requires API-Manager 7.7-20200130 or newer
Swagger 2.0	JSON/YAML	Yes	Yes	Fully supported
Swagger 1.2	JSON/YAML	No	Yes	Fully supported
Graphql	Graphql schema and introspection json	No	Yes	Fully supported
OData V2	XML(EDMX)	Yes	Yes (1.5.0)	Is automatically converted into an OpenAPI 3 specification. Requires API-Manager 7.7-20200130 or newer
OData V3	-	No	No	Not supported (use OData V2 or V4)
OData V4	XML(EDMX)	Yes	Yes	Is automatically converted into an OpenAPI 3 specification. Requires API-Manager 7.7-20200130 or newer
WADL	XML	No	Yes	Fully supported
WSDL	XML	No	Yes	Parameter BackendBasepath is not supported for WSDL. Must be URL reference.

Watch the video below to learn how easy it is to use the APIM-CLI to register an OData V2 service description as an OpenAPI 3.0 API specification in the API Management Platform.