github.com/cloudfoundry/cli@v7.1.0+incompatible/doc/v7-plugin-api-changes.md (about)

     1  # Updates to the V7 Plugin API Interface
     2  
     3  This document lists the differences in the objects the V7 Plugin API returns compared to V6.
     4  
     5  
     6  ## Methods that have changed
     7  
     8  ### CliCommand
     9  
    10  With the V6 CLI plugins that used `CliCommand` to run a `cf` command were
    11  actually calling into versions of these commands that were different to those
    12  accessible to a user from the command line.
    13  
    14  With the V7 CLI plugin authors will now see that command output reflects the current
    15  implementation of those commands.
    16  
    17  Plugins that inspect the output of `CliCommand` will need to be updated. We
    18  recommend that if you are writing a plugin you try to depend as little as
    19  possible on this output as it is subject to change.
    20  
    21  #### Error handling
    22  
    23  One significant change between older command implementations and the current
    24  versions is that many newer commands now use `stderr` to report warnings
    25  or failures.
    26  
    27  We have not yet extended the plugin API to expose output on `stderr`.
    28  
    29  When an error occurred the V6 CLI plugin API would return specific errors.
    30  Currently the new plugin API only returns a generic error for all error cases.
    31  
    32  ### GetApp
    33  Model changes
    34  
    35  V6
    36  ```json
    37  {
    38    "Guid": "defbb5bb-f010-4e4c-9841-60f641dd5bd4",
    39    "Name": "some-app",
    40    "BuildpackUrl": "",
    41    "Command": "",
    42    "DetectedStartCommand": "bundle exec rackup config.ru -p $PORT",
    43    "DiskQuota": 1024,
    44    "EnvironmentVars": null,
    45    "InstanceCount": 1,
    46    "Memory": 32,
    47    "RunningInstances": 1,
    48    "HealthCheckTimeout": 0,
    49    "State": "started",
    50    "SpaceGuid": "17586e2d-4df8-4879-b995-03d59a730e95",
    51    "PackageUpdatedAt": "2020-01-14T22:50:20Z",
    52    "PackageState": "STAGED",
    53    "StagingFailedReason": "",
    54    "Stack": {
    55      "Guid": "881b268c-d234-4c08-b5c5-50099ccb02bc",
    56      "Name": "cflinuxfs3",
    57      "Description": ""
    58    },
    59    "Instances": [
    60      {
    61        "State": "running",
    62        "Details": "",
    63        "Since": "2020-01-14T14:51:28-08:00",
    64        "CpuUsage": 0.0030685568679712145,
    65        "DiskQuota": 1073741824,
    66        "DiskUsage": 94228480,
    67        "MemQuota": 33554432,
    68        "MemUsage": 15935488
    69      }
    70    ],
    71    "Routes": [
    72      {
    73        "Guid": "93f82997-a2e8-406e-a4fd-f7c6d0d0fce5",
    74        "Host": "some-app",
    75        "Domain": {
    76          "Guid": "c0a63884-1260-4492-bf3c-119ed2c8a131",
    77          "Name": "example.com"
    78        },
    79        "Path": "",
    80        "Port": 0
    81      }
    82    ],
    83    "Services": null
    84  }
    85  ```
    86  
    87  V7
    88  ```json
    89  {
    90    "Name": "some-app",
    91    "GUID": "defbb5bb-f010-4e4c-9841-60f641dd5bd4",
    92    "StackName": "",
    93    "State": "STARTED",
    94    "LifecycleType": "buildpack",
    95    "LifecycleBuildpacks": null,
    96    "Metadata": null,
    97    "ProcessSummaries": [
    98      {
    99        "GUID": "defbb5bb-f010-4e4c-9841-60f641dd5bd4",
   100        "Type": "web",
   101        "Command": "bundle exec rackup config.ru -p $PORT",
   102        "HealthCheckType": "port",
   103        "HealthCheckEndpoint": "",
   104        "HealthCheckInvocationTimeout": 0,
   105        "HealthCheckTimeout": 0,
   106        "Instances": 1,
   107        "MemoryInMB": {
   108          "IsSet": true,
   109          "Value": 32
   110        },
   111        "DiskInMB": {
   112          "IsSet": true,
   113          "Value": 1024
   114        },
   115        "Sidecars": null,
   116        "InstanceDetails": [
   117          {
   118            "CPU": 0.003201964487972746,
   119            "Details": "",
   120            "DiskQuota": 1073741824,
   121            "DiskUsage": 94228480,
   122            "Index": 0,
   123            "IsolationSegment": "",
   124            "MemoryQuota": 33554432,
   125            "MemoryUsage": 15441920,
   126            "State": "RUNNING",
   127            "Type": "web",
   128            "Uptime": 94000000000
   129          }
   130        ]
   131      },
   132      {
   133        "GUID": "bf024163-6e42-45a7-a1e1-07e14aaf899b",
   134        "Type": "worker",
   135        "Command": "bundle exec rackup config.ru",
   136        "HealthCheckType": "process",
   137        "HealthCheckEndpoint": "",
   138        "HealthCheckInvocationTimeout": 0,
   139        "HealthCheckTimeout": 0,
   140        "Instances": 0,
   141        "MemoryInMB": {
   142          "IsSet": true,
   143          "Value": 32
   144        },
   145        "DiskInMB": {
   146          "IsSet": true,
   147          "Value": 1024
   148        },
   149        "Sidecars": null,
   150        "InstanceDetails": null
   151      }
   152    ],
   153    "Routes": [
   154      {
   155        "GUID": "93f82997-a2e8-406e-a4fd-f7c6d0d0fce5",
   156        "SpaceGUID": "17586e2d-4df8-4879-b995-03d59a730e95",
   157        "DomainGUID": "c0a63884-1260-4492-bf3c-119ed2c8a131",
   158        "Host": "some-app",
   159        "Path": "",
   160        "DomainName": "example.com",
   161        "SpaceName": "some-space",
   162        "URL": "some-app.example.com",
   163        "Destinations": [
   164          {
   165            "GUID": "12c6dc1d-9a31-4deb-b0fd-5563936adae0",
   166            "App": {
   167              "GUID": "defbb5bb-f010-4e4c-9841-60f641dd5bd4",
   168              "Process": {
   169                "Type": "web"
   170              }
   171            }
   172          }
   173        ],
   174        "Metadata": {
   175          "Labels": {}
   176        }
   177      }
   178    ],
   179    "CurrentDroplet": {
   180      "GUID": "0110f8db-f426-4aad-87d1-4106050cd129",
   181      "State": "STAGED",
   182      "CreatedAt": "2020-01-14T22:51:13Z",
   183      "Stack": "cflinuxfs3",
   184      "Image": "",
   185      "Buildpacks": [
   186        {
   187          "Name": "ruby_buildpack",
   188          "DetectOutput": "ruby"
   189        }
   190      ]
   191    }
   192  }
   193  ```
   194  
   195  Not targeted errors:
   196  
   197  cf6: `No org and space targeted, use 'cf target -o ORG -s SPACE' to target an org and space`
   198  
   199  cf7:
   200  
   201  `No organization targeted.`
   202  
   203  `No space targeted`
   204  
   205  ### GetCurrentSpace
   206  
   207  V6
   208  ```json
   209  {
   210    "Guid": "17586e2d-4df8-4879-b995-03d59a730e95",
   211    "Name": "some-space"
   212  }
   213  ```
   214  
   215  V7
   216  ```json
   217  {
   218    "Name": "some-space",
   219    "GUID": "17586e2d-4df8-4879-b995-03d59a730e95"
   220  }
   221  ```
   222  
   223  #### Error Changes
   224  
   225  When an org isn't targeted:
   226  
   227  V6 : Doesn't report an error, and returns an empty space object (error)
   228  
   229  V7 : Error: no organization targeted
   230  
   231  When a space isn't targeted:
   232  
   233  V6 : Doesn't report an error, and returns an empty space object (error)
   234  
   235  V7 : Error: no space targeted
   236  
   237  ### GetCurrentOrg
   238  Model Changes
   239  
   240  V6
   241  ```json
   242  {
   243    "Guid": "d00d3542-26d2-48eb-9c39-532c10ddf487",
   244    "Name": "some-org",
   245    "QuotaDefinition": {
   246      "Guid": "",
   247      "Name": "",
   248      "MemoryLimit": 0,
   249      "InstanceMemoryLimit": 0,
   250      "RoutesLimit": 0,
   251      "ServicesLimit": 0,
   252      "NonBasicServicesAllowed": false
   253    }
   254  }
   255  ```
   256  
   257  V7
   258  ```json
   259  {
   260    "Name": "some-org",
   261    "GUID": "d00d3542-26d2-48eb-9c39-532c10ddf487"
   262  }
   263  ```
   264  #### Error Changes
   265  
   266  When an org isn't targeted:
   267  
   268  V6 : Doesn't report an error, and returns an empty org object (error)
   269  
   270  V7 : Error: no organization targeted
   271  
   272  ### GetOrg
   273  
   274  #### Model changes
   275  The main difference here is the removal of Quota information from GetOrg, in our
   276  User research we found no uses of this, we also added Metadata to the V7 object
   277  
   278  V6
   279  ```json
   280  {
   281    "Guid": "d00d3542-26d2-48eb-9c39-532c10ddf487",
   282    "Name": "some-org",
   283    "QuotaDefinition": {
   284      "Guid": "",
   285      "Name": "default",
   286      "MemoryLimit": 102400,
   287      "InstanceMemoryLimit": -1,
   288      "RoutesLimit": 1000,
   289      "ServicesLimit": -1,
   290      "NonBasicServicesAllowed": true
   291    },
   292    "Spaces": [
   293      {
   294        "Guid": "17586e2d-4df8-4879-b995-03d59a730e95",
   295        "Name": "some-space"
   296      }
   297    ],
   298    "Domains": [
   299      {
   300        "Guid": "c0a63884-1260-4492-bf3c-119ed2c8a131",
   301        "Name": "example.com",
   302        "OwningOrganizationGuid": "",
   303        "Shared": true
   304      }
   305    ],
   306    "SpaceQuotas": null
   307  }
   308  ```
   309  
   310  V7
   311  
   312  ```json
   313  {
   314    "Name": "some-org",
   315    "GUID": "d00d3542-26d2-48eb-9c39-532c10ddf487",
   316    "Metadata": {
   317      "Labels": {
   318        "some-key": "some-value"
   319      }
   320    },
   321    "Spaces": [
   322      {
   323        "Name": "some-space",
   324        "GUID": "17586e2d-4df8-4879-b995-03d59a730e95",
   325        "Metadata": {
   326          "Labels": null
   327        }
   328      }
   329    ],
   330    "Domains": [
   331      {
   332        "Name": "example.com",
   333        "GUID": "c0a63884-1260-4492-bf3c-119ed2c8a131"
   334      }
   335    ]
   336  }
   337  ```
   338  
   339  ### GetSpace
   340  
   341  #### Model changes
   342  The main difference is that the V7 plugin will return only the space name and GUID, as well as its Metadata (currently existing uses of the V6 plugin are only using the `Guid` field).
   343  
   344  V6
   345  ```json
   346  {
   347    "Guid": "17586e2d-4df8-4879-b995-03d59a730e95",
   348    "Name": "some-space",
   349    "Organization": {
   350      "Guid": "d00d3542-26d2-48eb-9c39-532c10ddf487",
   351      "Name": "some-org"
   352    },
   353    "Applications": [
   354      {
   355        "Name": "some-app",
   356        "Guid": "defbb5bb-f010-4e4c-9841-60f641dd5bd4"
   357      }
   358    ],
   359    "ServiceInstances": null,
   360    "Domains": [
   361      {
   362        "Guid": "c0a63884-1260-4492-bf3c-119ed2c8a131",
   363        "Name": "example.com",
   364        "OwningOrganizationGuid": "",
   365        "Shared": true
   366      }
   367    ],
   368    "SecurityGroups": [
   369      {
   370        "Name": "public_networks",
   371        "Guid": "8a1f1ebf-41a4-4739-ac9f-e9a52e3e583c",
   372        "Rules": [
   373          {
   374            "destination": "0.0.0.0-9.255.255.255",
   375            "protocol": "all"
   376          }
   377        ]
   378      }
   379    ],
   380    "SpaceQuota": {
   381      "Guid": "",
   382      "Name": "",
   383      "MemoryLimit": 0,
   384      "InstanceMemoryLimit": 0,
   385      "RoutesLimit": 0,
   386      "ServicesLimit": 0,
   387      "NonBasicServicesAllowed": false
   388    }
   389  }
   390  ```
   391  
   392  V7
   393  
   394  ```json
   395  {
   396    "Name": "some-space",
   397    "GUID": "17586e2d-4df8-4879-b995-03d59a730e95",
   398    "Metadata": {
   399      "Labels": {
   400        "some-key": "some-value"
   401      }
   402    }
   403  }
   404  ```
   405  
   406  ### GetApps
   407  #### Model Changes
   408  
   409  V6
   410  ```json
   411  [
   412    {
   413      "Name": "some-app",
   414      "Guid": "defbb5bb-f010-4e4c-9841-60f641dd5bd4",
   415      "State": "started",
   416      "TotalInstances": 1,
   417      "RunningInstances": 1,
   418      "Memory": 32,
   419      "DiskQuota": 1024,
   420      "Routes": [
   421        {
   422          "Guid": "93f82997-a2e8-406e-a4fd-f7c6d0d0fce5",
   423          "Host": "some-app",
   424          "Domain": {
   425            "Guid": "c0a63884-1260-4492-bf3c-119ed2c8a131",
   426            "Name": "example.com",
   427            "OwningOrganizationGuid": "",
   428            "Shared": false
   429          }
   430        }
   431      ]
   432    }
   433  ]
   434  ```
   435  
   436  V7
   437  ```json
   438  [
   439    {
   440      "Name": "some-app",
   441      "GUID": "defbb5bb-f010-4e4c-9841-60f641dd5bd4",
   442      "StackName": "cflinuxfs3",
   443      "State": "STARTED",
   444      "LifecycleType": "buildpack",
   445      "LifecycleBuildpacks": null,
   446      "Metadata": {
   447        "Labels": {
   448          "some-key": "some-value"
   449        }
   450      }
   451    }
   452  ]
   453  ```
   454  
   455  
   456  #### Not-targeted errors
   457  
   458  When no space is targeted:
   459  
   460  V6: Returns error: `No org and space targeted, use 'cf target -o ORG -s SPACE' to target an org and space`
   461  
   462  V7: Returns error: `no space targeted`
   463  
   464  ### Username
   465  
   466  No interface changes
   467  
   468  #### Not logged in behaviour
   469  
   470  V6: Returns empty string with no error
   471  
   472  V7: Returns empty string with error `not logged in`
   473  
   474  ### GetSpaces
   475  #### Model Changes
   476  
   477  V6:
   478  ```json
   479  [
   480    {
   481      "Guid": "17586e2d-4df8-4879-b995-03d59a730e95",
   482      "Name": "some-space"
   483    }
   484  ]
   485  ```
   486  
   487  V7:
   488  ```json
   489  [
   490    {
   491      "Name": "some-space",
   492      "GUID": "17586e2d-4df8-4879-b995-03d59a730e95",
   493      "Metadata": {
   494        "Labels": {
   495          "some-key": "some-value"
   496        }
   497      }
   498    }
   499  ]
   500  ```
   501  
   502  ### IsSSLDisabled (Renamed to IsSkipSSLValidation in V7)
   503  
   504  The only difference in this method is that it was renamed from the V6
   505  `IsSSLDisabled` to the V7 `IsSkipSSLValidation`
   506  
   507  
   508  ## Methods that have not changed
   509  
   510  AccessToken
   511  ApiEndpoint
   512  IsLoggedIn
   513