CAMARA_common.yaml

openapi: 3.0.3
info:
 title: Camara common data types
 description: Common data types for Camara APIs
 contact:
  email: sp-com@lists.camaraproject.org
 license:
  name: Apache 2.0
  url: https://www.apache.org/licenses/LICENSE-2.0.html
 version: 0.4.0
paths: {}
components:
 schemas:
  TimePeriod:
   properties:
    startDate:
     type: string
     format: date-time
     description: An instant of time, starting of the TimePeriod.
    endDate:
     type: string
     format: date-time
     description: An instant of time, ending of the TimePeriod. If not included, then the period has no ending date.
   required:
    - startDate
  ErrorInfo:
   type: object
   required:
    - message
    - status
    - code
   properties:
    message:
     type: string
     description: A human readable description of what the event represent
    status:
     type: integer
     description: HTTP response status code
    code:
     type: string
     description: Friendly Code to describe the error
  Device:
   description: |
    End-user equipment able to connect to a mobile network. Examples of devices include smartphones or IoT sensors/actuators.
        The developer can choose to provide the below specified device identifiers:
        * `ipv4Address`
        * `ipv6Address`
        * `phoneNumber`
        * `networkAccessIdentifier`
        NOTE: the MNO might support only a subset of these options. The API invoker can provide multiple identifiers to be compatible across different MNOs. In this case the identifiers MUST belong to the same device.
   type: object
   properties:
    phoneNumber:
     $ref: "#/components/schemas/PhoneNumber"
    networkAccessIdentifier:
     $ref: "#/components/schemas/NetworkAccessIdentifier"
    ipv4Address:
     $ref: "#/components/schemas/DeviceIpv4Addr"
    ipv6Address:
     $ref: "#/components/schemas/DeviceIpv6Address"
   minProperties: 1

  PhoneNumber:
   description: A public identifier addressing a telephone subscription. In mobile networks it corresponds to the MSISDN (Mobile Station International Subscriber Directory Number). In order to be globally unique it has to be formatted in international format, according to E.164 standard, prefixed with '+'.
   type: string
   pattern: '^\+[1-9][0-9]{4,14}$'
   example: "+123456789"

  NetworkAccessIdentifier:
   description: A public identifier addressing a subscription in a mobile network. In 3GPP terminology, it corresponds to the GPSI formatted with the External Identifier ({Local Identifier}@{Domain Identifier}). Unlike the telephone number, the network access identifier is not subjected to portability ruling in force, and is individually managed by each operator.
   type: string
   example: "123456789@domain.com"

  DeviceIpv4Addr:
   type: object
   description: |
    The device should be identified by either the public (observed) IP address and port as seen by the application server, or the private (local) and any public (observed) IP addresses in use by the device (this information can be obtained by various means, for example from some DNS servers).

    If the allocated and observed IP addresses are the same (i.e. NAT is not in use) then  the same address should be specified for both publicAddress and privateAddress.

    If NAT64 is in use, the device should be identified by its publicAddress and publicPort, or separately by its allocated IPv6 address (field ipv6Address of the Device object)

    In all cases, publicAddress must be specified, along with at least one of either privateAddress or publicPort, dependent upon which is known. In general, mobile devices cannot be identified by their public IPv4 address alone.
   properties:
    publicAddress:
     $ref: "#/components/schemas/SingleIpv4Addr"
    privateAddress:
     $ref: "#/components/schemas/SingleIpv4Addr"
    publicPort:
     $ref: "#/components/schemas/Port"
   anyOf:
    - required: [publicAddress, privateAddress]
    - required: [publicAddress, publicPort]
   example:
    publicAddress: "84.125.93.10"
    publicPort: 59765

  SingleIpv4Addr:
   description: A single IPv4 address with no subnet mask
   type: string
   format: ipv4
   example: "84.125.93.10"

  Port:
   description: TCP or UDP port number
   type: integer
   minimum: 0
   maximum: 65535

  DeviceIpv6Address:
   description: |
    The device should be identified by the observed IPv6 address, or by any single IPv6 address from within the subnet allocated to the device (e.g. adding ::0 to the /64 prefix).
   type: string
   format: ipv6
   example: 2001:db8:85a3:8d3:1319:8a2e:370:7344

 responses:
  InvalidArgument:
   description: Invalid Argument
   content:
    application/json:
     schema:
      $ref: "#/components/schemas/ErrorInfo"
     example:
      status: 400
      code: INVALID_ARGUMENT
      message: Client specified an invalid argument, request body or query param
  Conflict:
   description: Conflict
   content:
    application/json:
     schema:
      $ref: "#/components/schemas/ErrorInfo"
     example:
      status: 409
      code: CONFLICT
      message:  Request could not be processed due to a conflict
  FailedPrecondition:
   description: Failed precondition
   content:
    application/json:
     schema:
      $ref: "#/components/schemas/ErrorInfo"
     example:
      status: 412
      code: FAILED_PRECONDITION
      message: Request cannot be executed in the current system state.
  OutOfRange:
   description: Out of Range
   content:
    application/json:
     schema:
      $ref: "#/components/schemas/ErrorInfo"
     example:
      status: 400
      code: OUT_OF_RANGE
      message: Client specified an invalid range
  Unauthenticated:
   description: Not Authenticated
   content:
    application/json:
     schema:
      $ref: "#/components/schemas/ErrorInfo"
     example:
      status: 401
      code: UNAUTHENTICATED
      message: Request not authenticated due to missing, invalid, or expired
  PermissionDenied:
   description: Permission denied
   content:
    application/json:
     schema:
      $ref: "#/components/schemas/ErrorInfo"
     example:
      status: 403
      code: PERMISSION_DENIED
      message: Client does not have sufficient permissions to perform
  NotFound:
   description: Not Found
   content:
    application/json:
     schema:
      $ref: "#/components/schemas/ErrorInfo"
     example:
      status: 404
      code: NOT_FOUND
      message: The specified resource is not found.
  Aborted:
   description: Aborted
   content:
    application/json:
     schema:
      $ref: "#/components/schemas/ErrorInfo"
     example:
      status: 409
      code: ABORTED
      message: Request aborted.
  AlreadyExists:
   description: Already Exists
   content:
    application/json:
     schema:
      $ref: "#/components/schemas/ErrorInfo"
     example:
      status: 409
      code: ALREADY_EXISTS
      message: The resource that a client tried to create already exists.
  TooManyRequests:
   description: Too Many Requests
   content:
    application/json:
     schema:
      $ref: "#/components/schemas/ErrorInfo"
     example:
      status: 429
      code: TOO_MANY_REQUESTS
      message: Either out of resource quota or reaching rate limiting.
  Internal:
   description: Internal Error
   content:
    application/json:
     schema:
      $ref: "#/components/schemas/ErrorInfo"
     example:
      status: 500
      code: INTERNAL
      message: Unknown server error.Typically a server bug.
  BadGateway:
   description: Bad Gateway
   content:
    application/json:
     schema:
      $ref: "#/components/schemas/ErrorInfo"
     example:
      status: 502
      code: BAD_GATEWAY
      message: Couldn't reach an upstream internal service.
  Unavailable:
   description: Service Unavailable
   content:
    application/json:
     schema:
      $ref: "#/components/schemas/ErrorInfo"
     example:
      status: 503
      code: UNAVAILABLE
      message: Service unavailable
  Timeout:
   description: Timeout
   content:
    application/json:
     schema:
      $ref: "#/components/schemas/ErrorInfo"
     example:
      status: 504
      code: TIMEOUT
      message: Request timeout exceeded
  NotImplemented:
   description: Not Implemented
   content:
    application/json:
     schema:
      $ref: "#/components/schemas/ErrorInfo"
     example:
      status: 501
      code: NOT_IMPLEMENTED
      message: This functionality is not implemented yet
  AuthenticationRequired:
   description: Authentication Required
   content:
    application/json:
     schema:
      $ref: "#/components/schemas/ErrorInfo"
     example:
      status: 401
      code: AUTHENTICATION_REQUIRED
      message: New authentication is required
  NotFoundAndOutOfRange:
   description: Out Of Range and Not Found
   content:
    application/json:
     schema:
      $ref: "#/components/schemas/ErrorInfo"
     examples:
      OutOfRange:
       value:
        status: 404
        code: OUT_OF_RANGE
        message: Out Of Range
      NotFound:
       value:
        status: 404
        code: NOT_FOUND
        message: Not found
  MethodNotAllowed:
   description: Method not allowed
   content:
    application/json:
     schema:
      $ref: "#/components/schemas/ErrorInfo"
     example:
      status: 405
      code: METHOD_NOT_ALLOWED
      message: The requested method is not allowed/supported on the target
  NotAcceptable:
   description: Not Acceptable
   content:
    application/json:
     schema:
      $ref: "#/components/schemas/ErrorInfo"
     example:
      status: 406
      code: NOT_ACCEPTABLE
      message: The server can't produce a response matching the content requested
       by the client through Accept-* headers
  UnsupportedMediaType:
   description: Unsupported Media Type
   content:
    application/json:
     schema:
      $ref: "#/components/schemas/ErrorInfo"
     example:
      status: 415
      code: UNSUPPORTED_MEDIA_TYPE
      message: The server refuses to accept the request because the payload format
       is in an unsupported format.