API Gateway and OpenAPI issues

MIP
, , , ,
1

Hello, I am working with API Gateway using openapi.yaml (NSwag generated C# client)

<OpenApiReference Include="Model\MilestoneOpenapi.yaml" ClassName="APIGatewayClient" CodeGenerator="NSwagCSharp" Namespace="Milestone" />

  1. Where can I find most recent openapi definition? https://download.milestonesys.com/ApiGateway/openapi.yaml seems to be not up to date with 2022 R2. Please consider per VMS version file versioning.

  2. Almost all queries failing (on deserializing relations) since openapi expects type array but query returns object.

        relations:
          type: array
          items:
            $ref: '#/components/schemas/links_ptzPresets'

            "relations": {
                "parent": {
                    "type": "cameras",
                    "id": "da7292ad-xxxx-49a0-bb86-0316b035e234"
                },
                "self": {
                    "type": "ptzPresets",
                    "id": "7484408d-xxxx-4b25-8720-f5ee1d8f3415"
                }
            }
  1. This is hard to work when sometimes API return array and sometimes it return object. Can you always return array but with one element inside? For example:
// https://...:443/api/rest/v1/cameras/....1/streams
{
    "array": [
        {
            "displayName": "Streams",
            "stream": [
                {
                    "displayName": "Stream #1",
                    "name": "Stream #1",
....
}

// https://...:443/api/rest/v1/cameras/....2/streams
{
    "array": [
        {
            "displayName": "Streams",
            "stream": {
                "displayName": "Video stream 1",
                "name": "Video stream 1",
                "streamReferenceId": "28DC44C3-079E-4C94-8EC9-60363451EB40",
                "liveDefault": true,
                "liveMode": "WhenNeeded",
                "record": true
            },
...
}
  1. According to openapi getOneptzPresetsInAcameras should return “array” but it does return “data”
// https://....:443/api/rest/v1/cameras/.../ptzpresets/.....3
{
    "data": {
        "displayName": "Home",
        "id": "75fa0e5e-a9c5-406b-ab29-5f20ead5efb3",
...
}

// Openapi:
      responses:
        '200':
          description: OK
          content:
            'application/json':
              schema:
                type: object
                properties:
                  array:
                    type: array
                    items:
                      $ref: '#/components/schemas/ptzPresets'
2
  1. https://doc.developer.milestonesys.com/mipvmsapi/#section/Introduction/Download-OpenAPI-specification

Regarding 2) - 4), I will ask Milestone Development, so let me get back to you later.

3

Thanks! Updated the definition. It seems like 2) and 4) is not an issue anymore, but 3) is still problematic.

One more finding, GetAllsettingsInAcamerasAsync. Property names does not match

cameraPtz != ptz

streams != stream

generalSettings != settings

Also streams[x].targetBitrate and streams[x].fps are not included in openapi def

//https://...:443/api/rest/v1/cameras/.../settings
{
//...
            "ptz": { ... },
            "generalSettings": { ... }
            "stream": [{ "fPS": "8.0", "targetBitrate": 2000, ... }]
// ...
}
 
//Openapi
    settings:
      type: object
      description: 'Settings'
      properties:
        settings:
          $ref: '#/components/schemas/settings_childItem'
        cameraPtz:
          $ref: '#/components/schemas/cameraPtz_childItem'
        streams:
          type: array
          readOnly: true
          items:
            $ref: '#/components/schemas/streams_childItem'
4

Regarding (3), Milestone Development will start an investigation. Let me get back to you when we get a news from them.

5

Regarding 3), I tested 2022 R2(server and API gateway) and I got object, not array. Then I tested 2022 R3 which will be released on 11th of October, worked fine and I got array. So in between, there must be a fix.

Can you upgrade 2022 R3 VMS when it releases? Or shall we make a hotfix for2022 R2 for the issue?

6

I can wait for R3 release