LocationAPI.json 54.5 KB
Newer Older
{
  "swagger": "2.0",
  "info": {
    "title": "Location API",
    "version": "1.1.1",
    "description": "The ETSI MEC ISG MEC012 Location API described using OpenAPI. The API is based on the Open Mobile Alliance's specification RESTful Network API for Zonal Presence",
admin_forge's avatar
admin_forge committed
      "name": "BSD-3-Clause",
      "url": "https://forge.etsi.org/legal-matters"
    "description": "ETSI MEC013 V1.1.1 Location Service API",
    "url": "http://www.etsi.org/deliver/etsi_gs/MEC/001_099/013/01.01.01_60/gs_mec013v010101p.pdf"
  },
  "host": "127.0.0.1:8081",
  "schemes": [
    "http",
    "https"
  ],
  "consumes": [
    "application/json"
  ],
  "produces": [
    "application/json"
  ],
  "tags": [
    {
      "name": "zones"
    },
    {
      "name": "users"
    },
    {
      "name": "subscriptions"
    }
  ],
  "parameters": {
    "Body.UserTrackingSubscription": {
      "name": "userTrackingSubscription",
      "in": "body",
      "description": "User Tracking Subscription",
      "required": true,
      "schema": {
        "$ref": "#/definitions/UserTrackingSubscription"
      }
    },
    "Body.ZonalTrafficSubscription": {
      "name": "zonalTrafficSubscription",
      "in": "body",
      "description": "Zonal Traffic Subscription",
      "required": true,
      "schema": {
        "$ref": "#/definitions/ZonalTrafficSubscription"
      }
    },
    "Body.ZoneStatusSubscription": {
      "name": "zoneStatusSubscription",
      "in": "body",
      "description": "Zone Status Subscription",
      "required": true,
      "schema": {
        "$ref": "#/definitions/ZoneStatusSubscription"
      }
    },
    "Path.AccessPointId": {
      "name": "accessPointId",
      "in": "path",
      "description": "Access Point ID",
      "required": true,
      "type": "string"
    },
    "Path.SubscriptionId": {
      "name": "subscriptionId",
      "in": "path",
      "description": "Subscription ID",
      "required": true,
      "type": "string"
    },
    "Path.UserId": {
      "name": "userId",
      "in": "path",
      "description": "User ID",
      "required": true,
      "type": "string"
    },
    "Path.ZoneId": {
      "name": "zoneId",
      "in": "path",
      "description": "Zone ID",
      "required": true,
      "type": "string"
    },
    "Query.AccessPointId": {
      "name": "accessPointId",
      "in": "query",
      "description": "Identifier of access point, reference \"definitions\" for string format",
      "required": false,
      "type": "string"
    },
    "Query.InterestRealm": {
      "name": "interestRealm",
      "in": "query",
      "description": "Interest realm of access point (e.g. geographical area, a type of industry etc.).",
      "required": false,
      "type": "string"
    },
    "Query.ZoneId": {
      "name": "zoneId",
      "in": "query",
      "description": "Zone ID",
      "required": true,
      "type": "string"
    }
  },
  "paths": {
    "/zones": {
      "get": {
        "description": "Used to get a list of identifiers for zones authorized for use by the application.",
        "produces": [
          "application/json"
        ],
        "responses": {
          "200": {
            "description": "Successful response to a query regarding the status of a zone",
            "schema": {
              "properties": {
                "zoneList": {
                  "$ref": "#/definitions/ZoneList"
                }
              }
            },
            "examples": {
              "application/json": {
                "zoneList": {
                  "zone": [
                    {
                      "zoneId": "zone01",
                      "numberOfAccessPoints": "3",
                      "numberOfUnserviceableAccessPoints": "1",
                      "numberOfUsers": "10",
                      "resourceURL": "http://example.com/exampleAPI/location/v1/zones/zone01"
                    },
                    {
                      "zoneId": "zone02",
                      "numberOfAccessPoints": "12",
                      "numberOfUnserviceableAccessPoints": "0",
                      "numberOfUsers": "36",
                      "resourceURL": "http://example.com/exampleAPI/location/v1/zones/zone02"
                    }
                  ],
                  "resourceURL": "http://example.com/exampleAPI/location/v1/zones"
                }
              }
            }
          }
        }
      }
    },
    "/zones/{zoneId}": {
        "description": "Used to get the status of a zone.",
        "produces": [
          "application/json"
        ],
        "responses": {
          "200": {
            "description": "Successful response to a query regarding the status of a zone",
            "schema": {
              "properties": {
                "zoneInfo": {
                  "$ref": "#/definitions/ZoneInfo"
                }
              }
            },
            "examples": {
              "application/json": {
                "zoneInfo": {
                  "zoneId": "zone01",
                  "numberOfAccessPoints": "3",
                  "numberOfUnserviceableAccessPoints": "1",
                  "numberOfUsers": "10",
                  "resourceURL": "http://example.com/exampleAPI/location/v1/zones/zone01"
                }
              }
            }
          }
        }
      }
    },
    "/zones/{zoneId}/accessPoints": {
        "description": "Access point status can be retrieved for sets of access points matching attribute in the request.",
        "produces": [
          "application/json"
        ],
        "parameters": [
          {
            "$ref": "#/parameters/Query.InterestRealm"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response to a query a named set of access point status request",
            "schema": {
              "properties": {
                "accessPointList": {
                  "$ref": "#/definitions/AccessPointList"
                }
              }
            },
            "examples": {
              "application/json": {
                "accessPointList": {
                  "zoneId": "zone01",
                  "accessPoint": [
                    {
                      "accessPointId": "001010000000000000000000000000001",
                      "locationInfo": {
                        "latitude": "90.123",
                        "longitude": "80.123",
                        "altitude": "10.0",
                        "accuracy": "0"
                      },
                      "connectionType": "Macro",
                      "operationStatus": "Serviceable",
                      "numberOfUsers": "5",
                      "interestRealm": "LA",
                      "resourceURL": "http://example.com/exampleAPI/location/v1/zones/zone01/accessPoints/ap001"
                    },
                    {
                      "accessPointId": "001010000000000000000000000000010",
                      "locationInfo": {
                        "latitude": "91.123",
                        "longitude": "81.123",
                        "altitude": "12.0",
                        "accuracy": "1"
                      },
                      "connectionType": "Macro",
                      "operationStatus": "Unserviceable",
                      "numberOfUsers": "0",
                      "interestRealm": "DC",
                      "resourceURL": "http://example.com/exampleAPI/location/v1/zones/zone01/accessPoints/ap002"
                    },
                    {
                      "accessPointId": "001010000000000000000000000000011",
                      "locationInfo": {
                        "latitude": "93.123",
                        "longitude": "83.123",
                        "altitude": "16.0",
                        "accuracy": "3"
                      },
                      "connectionType": "Macro",
                      "operationStatus": "Serviceable",
                      "numberOfUsers": "5",
                      "interestRealm": "NJ",
                      "resourceURL": "http://example.com/exampleAPI/location/v1/zones/zone01/accessPoints/ap003"
                    }
                  ],
                  "resourceURL": "http://example.com/exampleAPI/location/v1/zones/zone01/accessPoints"
                }
              }
            }
          }
        }
      }
    },
    "/zones/{zoneId}/accessPoints/{accessPointId}": {
      "parameters": [
        {
          "$ref": "#/parameters/Path.ZoneId"
        },
        {
          "$ref": "#/parameters/Path.AccessPointId"
        }
      ],
        "tags": [
          "zones"
        ],
        "operationId": "zonesByIdGetApsById",
        "description": "Access point status can be retrieved for sets of access points matching attribute in the request.",
        "produces": [
          "application/json"
        ],
        "responses": {
          "200": {
            "description": "Successful response to a query a named set of access point status request",
            "schema": {
              "properties": {
                "accessPointInfo": {
                  "$ref": "#/definitions/AccessPointInfo"
                }
              }
            },
            "examples": {
              "application/json": {
                "accessPointInfo": {
                  "accessPointId": "001010000000000000000000000000001",
                  "locationInfo": {
                    "latitude": "90.123",
                    "longitude": "80.123",
                    "altitude": "10.0",
                    "accuracy": "0"
                  },
                  "connectionType": "Macro",
                  "operationStatus": "Serviceable",
                  "numberOfUsers": "5",
                  "interestRealm": "LA",
                  "resourceURL": "http://example.com/exampleAPI/location/v1/zones/zone001/accessPoints/ap001"
                }
              }
            }
          }
        }
      }
    },
    "/users": {
      "get": {
        "description": "Users currently using a zone may be retrieved for sets of access points matching attribute in the request",
        "produces": [
          "application/json"
        ],
        "parameters": [
          {
            "$ref": "#/parameters/Query.ZoneId"
          },
          {
            "$ref": "#/parameters/Query.AccessPointId"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response to a query users within a zone request",
            "schema": {
              "properties": {
                "userList": {
                  "$ref": "#/definitions/UserList"
                }
              }
            },
            "examples": {
              "application/json": {
                "userList": {
                  "user": [
                    {
                      "address": "acr:192.0.2.1",
                      "accessPointId": "001010000000000000000000000000001",
                      "zoneId": "zone01",
                      "resourceURL": "http://example.com/exampleAPI/location/v1/users/acr%3A192.0.2.1"
                    },
                    {
                      "address": "acr:192.0.2.2",
                      "accessPointId": "001010000000000000000000000000001",
                      "zoneId": "zone01",
                      "resourceURL": "http://example.com/exampleAPI/location/v1/users/acr%3A192.0.2.2"
                    },
                    {
                      "address": "acr:192.0.2.3",
                      "accessPointId": "001010000000000000000000000000010",
                      "zoneId": "zone01",
                      "resourceURL": "http://example.com/exampleAPI/location/v1/users/acr%3A192.0.2.3"
                    },
                    {
                      "address": "acr:192.0.2.4",
                      "accessPointId": "001010000000000000000000000000001",
                      "zoneId": "zone02",
                      "resourceURL": "http://example.com/exampleAPI/location/v1/users/acr%3A192.0.2.4"
                    },
                    {
                      "address": "acr:192.0.2.5",
                      "accessPointId": "001010000000000000000000000000010",
                      "zoneId": "zone02",
                      "resourceURL": "http://example.com/exampleAPI/location/v1/users/acr%3A192.0.2.5"
                    }
                  ],
                  "resourceURL": "http://example.com/exampleAPI/location/v1/users"
                }
              }
            }
          }
        }
      }
    },
    "/users/{userId}": {
        "description": "Users currently using a zone may be retrieved for sets of access points matching attribute in the request",
        "produces": [
          "application/json"
        ],
        "responses": {
          "200": {
            "description": "Successful response to a query users within a zone request",
            "schema": {
              "properties": {
                "userInfo": {
                  "$ref": "#/definitions/UserInfo"
                }
              }
            },
            "examples": {
              "application/json": {
                "userInfo": {
                  "address": "acr:192.0.2.1",
                  "accessPointId": "001010000000000000000000000000001",
                  "zoneId": "zone01",
                  "resourceURL": "http://example.com/exampleAPI/location/v1/users/acr%3A192.0.2.1",
                  "locationInfo": {
                    "latitude": "90.123",
                    "longitude": "80.123",
                    "altitude": "10.0",
                    "accuracy": "0"
                  },
                  "contextLocationInfo": "GroundFloor"
                }
              }
            }
          }
        }
      }
    },
    "/subscriptions/zonalTraffic": {
      "get": {
        "tags": [
          "subscriptions"
        ],
        "operationId": "zonalTrafficSubGet",
        "description": "This operation is used for retrieving all active subscriptions to zonal traffic change notifications.",
        "produces": [
          "application/json"
        ],
        "responses": {
          "200": {
            "description": "Response to retrieve zonal traffic subscriptions",
            "schema": {
              "type": "object",
              "properties": {
                "notificationSubscriptionList": {
                  "type": "object",
                  "properties": {
                    "zonalTrafficSubscription": {
                      "type": "array",
                      "items": {
                        "$ref": "#/definitions/ZonalTrafficSubscription"
                      }
                    },
                    "resourceURL": {
                      "$ref": "#/definitions/ResourceURL"
                    }
                  }
                }
              }
            },
            "examples": {
              "application/json": {
                "notificationSubscriptionList": {
                  "zonalTrafficSubscription": [
                    {
                      "clientCorrelator": "0123",
                      "resourceURL": "http://example.com/exampleAPI/location/v1/subscriptions/zonalTraffic/subscription123",
                      "callbackReference": {
                        "notifyURL": "http://clientApp.example.com/location_notifications/123456"
                      },
                      "zoneId": "zone01",
                      "interestRealm": "LA",
                      "userEventCriteria": "Transferring"
                    },
                    {
                      "clientCorrelator": "0124",
                      "resourceURL": "http://example.com/exampleAPI/location/v1/subscriptions/zonalTraffic/subscription124",
                      "callbackReference": {
                        "notifyURL": "http://clientApp.example.com/location_notifications/123457"
                      },
                      "zoneId": "zone02",
                      "interestRealm": "LA",
                      "userEventCriteria": "Transferring"
                    }
                  ],
                  "resourceURL": "http://example.com/exampleAPI/location/v1/zonalTraffic"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "subscriptions"
        ],
        "operationId": "zonalTrafficSubPost",
        "description": "This operation is used for creating a new subscription to zonal traffic change notification.",
        "produces": [
          "application/json"
        ],
        "parameters": [
          {
            "$ref": "#/parameters/Body.ZonalTrafficSubscription"
          }
        ],
        "responses": {
          "201": {
            "description": "Response to create new zonal traffic subscription",
            "schema": {
              "properties": {
                "zonalTrafficSubscription": {
                  "$ref": "#/definitions/ZonalTrafficSubscription"
                }
              }
            },
            "examples": {
              "application/json": {
                "zonalTrafficSubscription": {
                  "clientCorrelator": "0123",
                  "resourceURL": "http://example.com/exampleAPI/location/v1/subscriptions/zonalTraffic/subscription123",
                  "callbackReference": {
                    "notifyURL": "http://clientApp.example.com/location_notifications/123456"
                  },
                  "zoneId": "zone01",
                  "interestRealm": "LA",
                  "userEventCriteria": "Transferring"
                }
              }
            }
          }
        }
      }
    },
    "/subscriptions/zonalTraffic/{subscriptionId}": {
      "parameters": [
        {
          "$ref": "#/parameters/Path.SubscriptionId"
        }
      ],
        "tags": [
          "subscriptions"
        ],
        "operationId": "zonalTrafficSubGetById",
        "description": "This operation is used for updating an individual subscription to zonal traffic change notification.",
        "produces": [
          "application/json"
        ],
        "responses": {
          "200": {
            "description": "Response to retrieve individual zonal traffic subscription",
            "schema": {
              "properties": {
                "zonalTrafficSubscription": {
                  "$ref": "#/definitions/ZonalTrafficSubscription"
                }
              }
            },
            "examples": {
              "application/json": {
                "zonalTrafficSubscription": {
                  "clientCorrelator": "0123",
                  "resourceURL": "http://example.com/exampleAPI/location/v1/subscriptions/zonalTraffic/subscription123",
                  "callbackReference": {
                    "notifyURL": "http://clientApp.example.com/location_notifications/123456"
                  },
                  "zoneId": "zone01",
                  "interestRealm": "LA",
                  "userEventCriteria": "Transferring"
                }
              }
            }
          }
        }
      },
      "put": {
        "tags": [
          "subscriptions"
        ],
        "operationId": "zonalTrafficSubPutById",
        "description": "This operation is used for updating an individual subscription to zonal traffic change notification.",
        "produces": [
          "application/json"
        ],
        "parameters": [
          {
            "$ref": "#/parameters/Body.ZonalTrafficSubscription"
          }
        ],
        "responses": {
          "200": {
            "description": "Response to update individual zonal traffic subscription",
            "schema": {
              "properties": {
                "zonalTrafficSubscription": {
                  "$ref": "#/definitions/ZonalTrafficSubscription"
                }
              }
            },
            "examples": {
              "application/json": {
                "zonalTrafficSubscription": {
                  "clientCorrelator": "0123",
                  "resourceURL": "http://example.com/exampleAPI/location/v1/subscriptions/zonalTraffic/subscription123",
                  "callbackReference": {
                    "notifyURL": "http://clientApp.example.com/location_notifications/123456"
                  },
                  "zoneId": "zone01",
                  "interestRealm": "LA",
                  "userEventCriteria": "Transferring"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "subscriptions"
        ],
        "operationId": "zonalTrafficSubDelById",
        "description": "This operation is used for cancelling a subscription and stopping corresponding notifications.",
        "produces": [
          "application/json"
        ],
        "responses": {
          "204": {
            "description": "No content"
          }
        }
      }
    },
    "/subscriptions/userTracking": {
      "get": {
        "tags": [
          "subscriptions"
        ],
        "operationId": "userTrackingSubGet",
        "description": "This operation is used for retrieving all active subscriptions to user tracking change notifications.",
        "produces": [
          "application/json"
        ],
        "responses": {
          "200": {
            "description": "Response to retrieve user tracking subscriptions",
            "schema": {
              "type": "object",
              "properties": {
                "notificationSubscriptionList": {
                  "type": "object",
                  "properties": {
                    "userTrackingSubscription": {
                      "type": "array",
                      "items": {
                        "$ref": "#/definitions/UserTrackingSubscription"
                      }
                    },
                    "resourceURL": {
                      "$ref": "#/definitions/ResourceURL"
                    }
                  }
                }
              }
            },
            "examples": {
              "application/json": {
                "notificationSubscriptionList": {
                  "userTrackingSubscription": [
                    {
                      "clientCorrelator": "0123",
                      "resourceURL": "http://example.com/exampleAPI/location/v1/subscriptions/userTracking/subscription123",
                      "callbackReference": {
                        "notifyURL": "http://clientApp.example.com/location_notifications/123456"
                      },
                      "address": "acr:192.0.2.1",
                      "userEventCriteria": "Transferring"
                    },
                    {
                      "clientCorrelator": "0124",
                      "resourceURL": "http://example.com/exampleAPI/location/v1/subscriptions/userTracking/subscription124",
                      "callbackReference": {
                        "notifyURL": "http://clientApp.example.com/location_notifications/123456"
                      },
                      "address": "acr:192.0.2.2",
                      "userEventCriteria": "Transferring"
                    }
                  ],
                  "resourceURL": "http://example.com/exampleAPI/location/v1/subscriptions/userTracking"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "subscriptions"
        ],
        "operationId": "userTrackingSubPost",
        "description": "This operation is used for creating a new subscription to user tracking change notification",
        "produces": [
          "application/json"
        ],
        "parameters": [
          {
            "$ref": "#/parameters/Body.UserTrackingSubscription"
          }
        ],
        "responses": {
          "201": {
            "description": "Response to create new user tracking subscription",
            "schema": {
              "properties": {
                "userTrackingSubscription": {
                  "$ref": "#/definitions/UserTrackingSubscription"
                }
              }
            },
            "examples": {
              "application/json": {
                "userTrackingSubscription": {
                  "clientCorrelator": "0123",
                  "resourceURL": "http://example.com/exampleAPI/location/v1/subscriptions/userTracking/subscription123",
                  "callbackReference": {
                    "notifyURL": "http://clientApp.example.com/location_notifications/123456"
                  },
                  "address": "acr:192.0.2.1",
                  "userEventCriteria": "Transferring"
                }
              }
            }
          }
        }
      }
    },
    "/subscriptions/userTracking/{subscriptionId}": {
      "parameters": [
        {
          "$ref": "#/parameters/Path.SubscriptionId"
        }
      ],
        "tags": [
          "subscriptions"
        ],
        "operationId": "userTrackingSubGetById",
        "description": "This operation is used for retrieving an individual subscription to user tracking change notification.",
        "produces": [
          "application/json"
        ],
        "responses": {
          "200": {
            "description": "Response to retrieve individual user tracking subscription",
            "schema": {
              "properties": {
                "userTrackingSubscription": {
                  "$ref": "#/definitions/UserTrackingSubscription"
                }
              }
            },
            "examples": {
              "application/json": {
                "userTrackingSubscription": {
                  "clientCorrelator": "0123",
                  "resourceURL": "http://example.com/exampleAPI/location/v1/subscriptions/userTracking/subscription123",
                  "callbackReference": {
                    "notifyURL": "http://clientApp.example.com/location_notifications/123456"
                  },
                  "address": "acr:192.0.2.1",
                  "userEventCriteria": "Transferring"
                }
              }
            }
          }
        }
      },
      "put": {
        "tags": [
          "subscriptions"
        ],
        "operationId": "userTrackingSubPutById",
        "description": "This operation is used for updating an individual subscription to user tracking change notification.",
        "produces": [
          "application/json"
        ],
        "parameters": [
          {
            "$ref": "#/parameters/Body.UserTrackingSubscription"
          }
        ],
        "responses": {
          "200": {
            "description": "Response to update individual user tracking subscription",
            "schema": {
              "properties": {
                "userTrackingSubscription": {
                  "$ref": "#/definitions/UserTrackingSubscription"
                }
              }
            },
            "examples": {
              "application/json": {
                "userTrackingSubscription": {
                  "clientCorrelator": "0123",
                  "resourceURL": "http://example.com/exampleAPI/location/v1/subscriptions/userTracking/subscription123",
                  "callbackReference": {
                    "notifyURL": "http://clientApp.example.com/location_notifications/123456"
                  },
                  "address": "acr:192.0.2.1",
                  "userEventCriteria": "Transferring"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "subscriptions"
        ],
        "operationId": "userTrackingSubDelById",
        "description": "This operation is used for retrieving an individual subscription to user tracking change notification.",
        "produces": [
          "application/json"
        ],
        "responses": {
          "204": {
            "description": "No Content"
          }
        }
      }
    },
    "/subscriptions/zonalStatus": {
      "get": {
        "tags": [
          "subscriptions"
        ],
        "operationId": "zoneStatusGet",
        "description": "This operation is used for creating a new subscription to zone status change notification.",
        "produces": [
          "application/json"
        ],
        "responses": {
          "200": {
            "description": "Response to retrieve zone status subscriptions",
            "schema": {
              "type": "object",
              "properties": {
                "notificationSubscriptionList": {
                  "type": "object",
                  "properties": {
                    "zonalTrafficSubscription": {
                      "type": "array",
                      "items": {
                        "$ref": "#/definitions/ZoneStatusSubscription"
                      }
                    },
                    "resourceURL": {
                      "$ref": "#/definitions/ResourceURL"
                    }
                  }
                }
              }
            },
            "examples": {
              "application/json": {
                "notificationSubscriptionList": {
                  "zoneStatusSubscription": [
                    {
                      "clientCorrelator": "0123",
                      "resourceURL": "http://example.com/exampleAPI/location/v1/subscriptions/zoneStatus/subscription123",
                      "callbackReference": {
                        "notifyURL": "http://clientApp.example.com/location_notifications/123456"
                      },
                      "zoneId": "zone01",
                      "numberOfUsersZoneThreshold": "500",
                      "operationStatus": "Serviceable"
                    },
                    {
                      "clientCorrelator": "0124",
                      "resourceURL": "http://example.com/exampleAPI/location/v1/subscriptions/zoneStatus/subscription124",
                      "callbackReference": {
                        "notifyURL": "http://clientApp.example.com/location_notifications/123457"
                      },
                      "zoneId": "zone02",
                      "numberOfUsersAPThreshold": "50",
                      "operationStatus": "Serviceable"
                    }
                  ],
                  "resourceURL": "http://example.com/exampleAPI/location/v1/subscriptions/zoneStatus"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "subscriptions"
        ],
        "operationId": "zoneStatusPost",
        "description": "This operation is used for creating a new subscription to zone status change notification.",
        "produces": [
          "application/json"
        ],
        "parameters": [
          {
            "$ref": "#/parameters/Body.ZoneStatusSubscription"
          }
        ],
        "responses": {
          "201": {
            "description": "Response to create new zone status subscription",
            "schema": {
              "properties": {
                "zonalTrafficSubscription": {
                  "$ref": "#/definitions/ZoneStatusSubscription"
                }
              }
            },
            "examples": {
              "application/json": {
                "zoneStatusSubscription": {
                  "clientCorrelator": "0123",
                  "resourceURL": "http://example.com/exampleAPI/location/v1/subscriptions/zoneStatus/subscription123",
                  "callbackReference": {
                    "notifyURL": "http://clientApp.example.com/location_notifications/123456"
                  },
                  "zoneId": "zone01",
                  "numberOfUsersZoneThreshold": "500",
                  "operationStatus": "Serviceable"
                }
              }
            }
          }
        }
      }
    },
    "/subscriptions/zoneStatus/{subscriptionId}": {
      "parameters": [
        {
          "$ref": "#/parameters/Path.SubscriptionId"
        }
      ],
        "tags": [
          "subscriptions"
        ],
        "operationId": "zoneStatusGetById",
        "description": "This operation is used for retrieving an individual subscription to zone status change notification.",
        "produces": [
          "application/json"
        ],
        "responses": {
          "200": {
            "description": "Response to retrieve individual zone status subscription",
            "schema": {
              "properties": {
                "zoneStatusSubscription": {
                  "$ref": "#/definitions/ZoneStatusSubscription"
                }
              }
            },
            "examples": {
              "application/json": {
                "zoneStatusSubscription": {
                  "clientCorrelator": "0123",
                  "resourceURL": "http://example.com/exampleAPI/location/v1/subscriptions/zoneStatus/subscription123",
                  "callbackReference": {
                    "notifyURL": "http://clientApp.example.com/location_notifications/123456"
                  },
                  "zoneId": "zone01",
                  "numberOfUsersZoneThreshold": "500",
                  "operationStatus": "Serviceable"
                }
              }
            }
          }
        }
      },
      "put": {
        "tags": [
          "subscriptions"
        ],
        "operationId": "zoneStatusPutById",
        "description": "This operation is used for updating an individual subscription to zone status change notification.",
        "produces": [
          "application/json"
        ],
        "parameters": [
          {
            "$ref": "#/parameters/Body.ZoneStatusSubscription"
          }
        ],
        "responses": {
          "200": {
            "description": "Response to update individual zone status subscription",
            "schema": {
              "properties": {
                "zoneStatusSubscription": {
                  "$ref": "#/definitions/ZoneStatusSubscription"
                }
              }
            },
            "examples": {
              "application/json": {
                "zoneStatusSubscription": {
                  "clientCorrelator": "0123",
                  "resourceURL": "http://example.com/exampleAPI/location/v1/subscriptions/zoneStatus/subscription123",
                  "callbackReference": {
                    "notifyURL": "http://clientApp.example.com/location_notifications/123456"
                  },
                  "zoneId": "zone01",
                  "numberOfUsersZoneThreshold": "500",
                  "operationStatus": "Serviceable"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "subscriptions"
        ],
        "operationId": "zoneStatusDelById",
        "description": "This operation is used for cancelling a subscription and stopping corresponding notifications.",
        "produces": [
          "application/json"
        ],
        "responses": {
          "204": {
            "description": "No content"
          }
        }
      }
    }
  },
  "definitions": {
    "AccessPointId": {
      "description": "Identifier of access point, <E-CGI><Cell Portion ID> (reference ETSI TS 129 171). Where the E-CGI is made up of the PLMN and Cell Identity (28 bit string). Then the PLMN is made up of the 3 digit MCC & 2 or 3 digit MNC. The Cell Portion is an optional element",
      "type": "string",
      "example": "001010000000000000000000000000001"
    },
    "AccessPointInfo": {
      "description": "A type containing access point information.",
      "type": "object",
      "required": [
        "accessPointId",
        "connectionType",
        "operationStatus",
        "numberOfUsers",
        "resourceURL"
      ],
      "properties": {
        "accessPointId": {
          "$ref": "#/definitions/AccessPointId"
        },
        "locationInfo": {
          "$ref": "#/definitions/LocationInfo"
        },
        "connectionType": {
          "$ref": "#/definitions/ConnectionType"
        },
        "operationStatus": {
          "$ref": "#/definitions/OperationStatus"
        },
        "numberOfUsers": {
          "$ref": "#/definitions/NumberOfUsers"
        },
        "timezone": {
          "$ref": "#/definitions/Timezone"
        },
        "interestRealm": {
          "$ref": "#/definitions/InterestRealm"
        },
        "resourceURL": {
          "$ref": "#/definitions/ResourceURL"
        }
      }
    },
    "AccessPointList": {
      "description": "A type containing list of access points.",
      "type": "object",
      "required": [
        "zoneId",
        "resourceURL"
      ],
      "properties": {
        "zoneId": {
          "$ref": "#/definitions/ZoneId"
        },
        "accessPoint": {
          "description": "Collection of the access point information list.",
          "type": "array",
          "items": {
            "$ref": "#/definitions/AccessPointInfo"
          }
        },
        "resourceURL": {
          "$ref": "#/definitions/ResourceURL"
        }
      }
    },
    "Address": {
      "description": "Address of user (e.g. \"sip\" URI, \"tel\" URI, \"acr\" URI).",
      "type": "string",
      "format": "uri",
      "example": "acr:192.0.2.1"
    },
    "AncillaryInfo": {
      "description": "Reserved for future use.",
      "type": "string"
    },
    "CallbackData": {
      "description": "CallBackData if passed by the application during the associated ZonalTrafficSubscription and UserTrackingSubscription operation. See [REST_NetAPI_Common].",
      "type": "string",
      "example": "1234"
    },
    "CallbackReference": {
      "description": "Notification callback definition.",
      "type": "object",
      "required": [
        "notifyURL"
      ],
      "properties": {
        "notifyURL": {
          "$ref": "#/definitions/NotifyURL"
        }
      }
    },
    "ClientCorrelator": {
      "description": "Uniquely identifies this create subscription request. If there is a communication failure during the request, using the same clientCorrelator when retrying the request allows the operator to avoid creating a duplicate subscription.",
      "type": "string",
      "example": "0123"
    },
    "ConnectionType": {
      "description": "The connection type for the access point",
      "type": "string",
      "enum": [
        "Femto",
        "LTE-femto",
        "Smallcell",
        "LTE-smallcell",
        "Wifi",
        "Pico",
        "Micro",
        "Macro",
        "Wimax",
        "Unknown"
      ],
      "example": "Macro"
    },
    "ContextLocationInfo": {
      "description": "Contextual information of a user location (e.g., aisle, floor, room number, etc.)",
      "type": "string",
      "example": "GroundFloor"
    },
    "CurrentAccessPointId": {
      "description": "Zone ID",
      "type": "string",
      "example": "zone01"
    },
    "Duration": {
      "description": "Period (in seconds) of time notifications are provided for. If set to \"0\" (zero), a default duration time, which is specified by the service policy, will be used. If the parameter is omitted, the notifications will continue until the maximum duration time, which is specified by the service policy, unless the notifications are stopped by deletion of subscription for notifications. This element MAY be given by the client during resource creation in order to signal the desired lifetime of the subscription. The server MUST return in this element the period of time for which the subscription will still be valid.",
      "type": "string",
      "example": "0"
    },
    "InterestRealm": {
      "description": "Interest realm of access point (e.g. geographical area, a type of industry etc.).",
      "type": "string",
      "example": "LA"
    },
    "Link": {
      "description": "Link to other resources",
      "type": "object",
      "required": [
        "rel",
        "href"
      ],
      "properties": {
        "rel": {
          "description": "Describes the relationship between the URI and the resource.",
          "type": "object",
          "format": "string"
        },
        "href": {
          "description": "URI",
          "type": "object",
          "format": "anyURI"
        }
      }
    },
    "LocationInfo": {
      "description": "A type containing location information with latitude, longitude and altitude, in addition the accuracy of the information are provided.",
      "type": "object",
      "required": [
        "latitude",
        "longitude",
        "accuracy"
      ],
      "properties": {
        "latitude": {
          "type": "number",
          "format": "float",
          "example": "80.123"
        },
        "longitude": {
          "type": "number",
          "format": "float",
          "example": "70.123"
        },
        "altitude": {
          "type": "number",
          "format": "float",
          "example": "10.0"
        },
        "accuracy": {
          "type": "integer",
          "format": "int32",
          "example": "10"
        }
      }
    },
    "NotifyURL": {
      "description": "The URL of your own listener application.",
      "type": "string",
      "format": "url",
      "example": "http://clientApp.example.com/location_notifications/123456"
    },
    "NumberOfAccessPoints": {
      "description": "The number of access points within the zone",
      "type": "integer",
      "format": "uint32",
      "example": "10"
    },
    "NumberOfUnserviceableAccessPoints": {
      "description": "Number of inoperable access points within the zone.",
      "type": "integer",
      "format": "uint32",
      "example": "9"
    },
    "NumberOfUsers": {
      "description": "The number of users currently on the access point.",
      "type": "integer",
      "format": "uint32",
      "example": "7"
    },
    "NumberOfUsersAPThreshold": {
      "description": "Threshold number of users in an access point which if crossed shall cause a notification.",
      "type": "integer",
      "format": "uint32",
      "example": "20"
    },
    "NumberOfUsersInAP": {
      "description": "This element shall be present when ZoneStatusSubscription includes numberOfUsersAPThreshold element and the number of users in an access point exceeds the threshold defined in the subscription.",
      "type": "integer",
      "format": "uint32",
      "example": "12"
    },
    "NumberOfUsersInZone": {
      "description": "This element shall be present when ZoneStatusSubscription includes numberOfUsersZoneThreshold element and the number of users in a zone exceeds the threshold defined in this subscription.",
      "type": "integer",
      "format": "uint32",
      "example": "20"
    },
    "NumberOfUsersZoneThreshold": {
      "description": "Threshold number of users in a zone which if crossed shall cause a notification.",
      "type": "integer",
      "format": "uint32",
      "example": "40"
    },
    "OperationStatus": {
      "description": "The operation status of the access point",
      "type": "string",
      "enum": [
        "Serviceable",
        "Unserviceable",
        "Unknown"
      ],
      "example": "Serviceable"
    },
    "PreviousAccessPointId": {
      "description": "Zone ID",
      "type": "string",
      "example": "zone02"
    },
    "ResourceURL": {
      "description": "Self referring URL.",
      "type": "string",
      "format": "uri",
      "example": "http://example.com/exampleAPI/location/v1/subscriptions/userTracking/subscription123"
    },
    "Timestamp": {
      "description": "Indicates the time of day for zonal presence notification.",
      "type": "string",
      "format": "date-time",
      "example": "2017-01-01T02:51:43Z"
    },
    "Timezone": {
      "description": "Time zone of access point",
      "type": "string",
      "format": "date-time",
      "example": "2017-01-01T02:51:43Z"
    },
    "UserEventCriteria": {
      "description": "List of user event values to generate notifications for (these apply to address specified). If this element is missing, a notification is requested to be generated for any change in user event.",
      "type": "array",
      "items": {
        "$ref": "#/definitions/UserEventType"
      }
    },
    "UserEventType": {
      "description": "User event",
      "type": "string",
      "enum": [
        "Entering",
        "Leaving",
        "Transferring"
      ],
      "example": "Entering"
    },
    "UserInfo": {
      "description": "A type containing user information.",
      "type": "object",
      "required": [
        "address",
        "accessPointId",
        "zoneId",
        "resourceURL"
      ],
      "properties": {
        "address": {
          "$ref": "#/definitions/Address"
        },
        "accessPointId": {
          "$ref": "#/definitions/AccessPointId"
        },
        "zoneId": {
          "$ref": "#/definitions/ZoneId"
        },
        "resourceURL": {
          "$ref": "#/definitions/ResourceURL"
        },
        "locationInfo": {
          "$ref": "#/definitions/LocationInfo"
        },
        "contextLocationInfo": {
          "$ref": "#/definitions/ContextLocationInfo"
        },
        "ancillaryInfo": {
          "$ref": "#/definitions/AncillaryInfo"
        }
      }
    },
    "UserList": {
      "description": "A type containing list of users.",
      "type": "object",
      "required": [
        "resourceURL"
      ],
      "properties": {
        "user": {
          "description": "Collection of the zone information list.",
          "type": "array",
          "items": {
            "$ref": "#/definitions/UserInfo"
          }
        },
        "resourceURL": {
          "$ref": "#/definitions/ResourceURL"
        }
      }
    },
    "UserTrackingSubscription": {
      "description": "A type containing user tracking subscription.",
      "type": "object",
      "required": [
        "callbackReference",
        "address"
      ],
      "properties": {
        "clientCorrelator": {
          "$ref": "#/definitions/ClientCorrelator"
        },
        "callbackReference": {
          "$ref": "#/definitions/CallbackReference"
        },
        "address": {
          "$ref": "#/definitions/Address"
        },
        "userEventCriteria": {
          "$ref": "#/definitions/UserEventCriteria"
        },
        "resourceURL": {
          "$ref": "#/definitions/ResourceURL"
        }
      }
    },
    "ZonalPresenceNotification": {
      "description": "A type containing zonal presence notification",
      "type": "object",
      "required": [
        "zoneId",
        "address",
        "userEventType",
        "currentAccessPointId",
        "timestamp"
      ],
      "properties": {
        "callbackData": {
          "$ref": "#/definitions/CallbackData"
        },
        "zoneId": {
          "$ref": "#/definitions/ZoneId"
        },
        "address": {
          "$ref": "#/definitions/Address"
        },
        "interestRealm": {
          "$ref": "#/definitions/InterestRealm"
        },
        "userEventType": {
          "$ref": "#/definitions/UserEventType"
        },
        "currentAccessPointId": {
          "$ref": "#/definitions/CurrentAccessPointId"
        },
        "previousAccessPointId": {
          "$ref": "#/definitions/PreviousAccessPointId"
        },
        "timestamp": {
          "$ref": "#/definitions/Timestamp"
        },
        "link": {
          "description": "Link to other resources that are in relationship with this notification. The server SHOULD include a link to the related subscription. No other links are required or suggested by this specification.",
          "type": "array",
          "items": {
            "$ref": "#/definitions/Link"
          },
          "example": "rel=\"ZonalTrafficSubscription\" href=\"http://example.com/exampleAPI/location/v1/subscriptions/zonalTraffic/sub123\"/"
        }
      }
    },
    "ZonalTrafficSubscription": {
      "description": "A type containing zonal traffic subscription",
      "type": "object",
      "required": [
        "callbackReference",
        "zoneId"
      ],
      "properties": {
        "clientCorrelator": {
          "$ref": "#/definitions/ClientCorrelator"
        },
        "callbackReference": {
          "$ref": "#/definitions/CallbackReference"
        },
        "zoneId": {
          "$ref": "#/definitions/ZoneId"
        },
        "interestRealm": {
          "description": "Interest realms of access points within a zone (e.g. geographical area, a type of industry etc.).",
          "type": "array",
          "items": {
            "$ref": "#/definitions/InterestRealm"
          }
        },
        "userEventCriteria": {
          "description": "List of user event values to generate notifications for (these apply to zone identifier or all interest realms within zone identifier specified). If this element is missing, a notification is requested to be generated for any change in user event.",
          "type": "array",
          "items": {
            "$ref": "#/definitions/UserEventType"
          }
        },
        "duration": {
          "$ref": "#/definitions/Duration"
        },
        "resourceURL": {
          "$ref": "#/definitions/ResourceURL"
        }
      }
    },
    "ZoneId": {
      "description": "Identifier of zone",
      "type": "string",
      "example": "zone01"
    },
    "ZoneInfo": {
      "description": "A type containing zone information.",
      "type": "object",
      "required": [
        "zoneId",
        "numberOfAccessPoints",
        "numberOfUnservicableAccessPoints",
        "numberOfUsers",
        "resourceURL"
      ],
      "properties": {
        "zoneId": {
          "$ref": "#/definitions/ZoneId"
        },
        "numberOfAccessPoints": {
          "$ref": "#/definitions/NumberOfAccessPoints"
        },
        "numberOfUnservicableAccessPoints": {
          "$ref": "#/definitions/NumberOfUnserviceableAccessPoints"
        },
        "numberOfUsers": {
          "$ref": "#/definitions/NumberOfUsers"
        },
        "resourceURL": {
          "$ref": "#/definitions/ResourceURL"
        }
      }
    },
    "ZoneList": {
      "description": "Collection of the zone information list.",
      "type": "object",
      "required": [
        "resourceURL"
      ],
      "properties": {
        "zone": {
          "description": "Collection of the zone information list.",
          "type": "array",
          "items": {
            "$ref": "#/definitions/ZoneInfo"
          }
        },
        "resourceURL": {
          "$ref": "#/definitions/ResourceURL"
        }
      }
    },
    "ZoneStatusNotification": {
      "description": "A type containing zone status notification.",
      "type": "object",
      "required": [
        "zoneId",
        "timestamp"
      ],
      "properties": {
        "callbackData": {
          "$ref": "#/definitions/CallbackData"
        },
        "zoneId": {
          "$ref": "#/definitions/ZoneId"
        },
        "accessPointId": {
          "$ref": "#/definitions/AccessPointId"
        },
        "numberOfUsersInZone": {
          "$ref": "#/definitions/NumberOfUsersInZone"
        },
        "numberOfUsersInAP": {
          "$ref": "#/definitions/NumberOfUsersInAP"
        },
        "operationStatus": {
          "$ref": "#/definitions/OperationStatus"
        },
        "timestamp": {
          "$ref": "#/definitions/Timestamp"
        },
        "link": {
          "description": "Link to other resources that are in relationship with this notification. The server SHOULD include a link to the related subscription. No other links are required or suggested by this specification.",
          "type": "array",
          "items": {
            "$ref": "#/definitions/Link"
          },
          "example": "rel=\"ZonalStatusSubscription\" href=\"http://example.com/exampleAPI/location/v1/subscriptions/zonalStatus/sub123\""
        }
      }
    },
    "ZoneStatusSubscription": {
      "description": "A type containing zone status subscription.",
      "type": "object",
      "required": [
        "callbackReference",
        "zoneId"
      ],
      "properties": {
        "clientCorrelator": {
          "$ref": "#/definitions/ClientCorrelator"
        },
        "resourceURL": {
          "$ref": "#/definitions/ResourceURL"
        },
        "callbackReference": {
          "$ref": "#/definitions/CallbackReference"
        },
        "zoneId": {
          "$ref": "#/definitions/ZoneId"
        },
        "numberOfUsersZoneThreshold": {
          "$ref": "#/definitions/NumberOfUsersZoneThreshold"
        },
        "numberOfUsersAPThreshold": {
          "$ref": "#/definitions/NumberOfUsersAPThreshold"
        },
        "operationStatus": {
          "description": "List of operation status values to generate notifications for (these apply to all access points within a zone).",
          "type": "array",
          "items": {
            "$ref": "#/definitions/OperationStatus"
          }
        }
      }
    }
  }
}